From 2fe34b6444502079dc0b84365ce82dbc92de308e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 13 Apr 2024 14:06:49 +0200 Subject: Adding upstream version 6.17.2. Signed-off-by: Daniel Baumann --- docs/.gitignore | 16 ++ docs/.nojekyll | 0 docs/_static/ansible-lint.svg | 6 + docs/_static/images/ansible-lint-512.png | Bin 0 -> 13320 bytes docs/_static/images/favicon.ico | Bin 0 -> 15406 bytes docs/_static/images/logo_invert.png | Bin 0 -> 4280 bytes docs/_static/theme_overrides.css | 24 +++ docs/configuring.md | 73 +++++++ docs/contributing.md | 119 +++++++++++ docs/custom-rules.md | 112 +++++++++++ docs/google04e29a42ae6e6cbc.html | 1 + docs/images/favicon.ico | Bin 0 -> 15406 bytes docs/images/logo.png | Bin 0 -> 10993 bytes docs/images/logo.svg | 7 + docs/index.md | 28 +++ docs/installing.md | 113 +++++++++++ docs/licenses/LICENSE.mit.txt | 21 ++ docs/philosophy.md | 109 ++++++++++ docs/pkg/.gitignore | 2 + docs/profiles.md | 110 ++++++++++ docs/redirects.yml | 38 ++++ docs/rules/args.md | 1 + docs/rules/avoid-implicit.md | 1 + docs/rules/command-instead-of-module.md | 1 + docs/rules/command-instead-of-shell.md | 1 + docs/rules/deprecated-bare-vars.md | 1 + docs/rules/deprecated-local-action.md | 1 + docs/rules/deprecated-module.md | 1 + docs/rules/empty-string-compare.md | 1 + docs/rules/fqcn.md | 1 + docs/rules/galaxy.md | 1 + docs/rules/ignore-errors.md | 1 + docs/rules/index.md | 51 +++++ docs/rules/inline-env-var.md | 1 + docs/rules/internal-error.md | 1 + docs/rules/jinja.md | 1 + docs/rules/key-order.md | 1 + docs/rules/latest.md | 1 + docs/rules/literal-compare.md | 1 + docs/rules/load-failure.md | 1 + docs/rules/loop-var-prefix.md | 1 + docs/rules/meta-incorrect.md | 1 + docs/rules/meta-no-tags.md | 1 + docs/rules/meta-runtime.md | 1 + docs/rules/meta-video-links.md | 1 + docs/rules/name.md | 1 + docs/rules/no-changed-when.md | 1 + docs/rules/no-free-form.md | 1 + docs/rules/no-handler.md | 1 + docs/rules/no-jinja-when.md | 1 + docs/rules/no-log-password.md | 1 + docs/rules/no-prompting.md | 1 + docs/rules/no-relative-paths.md | 1 + docs/rules/no-same-owner.md | 1 + docs/rules/no-tabs.md | 1 + docs/rules/only-builtins.md | 1 + docs/rules/package-latest.md | 1 + docs/rules/parser-error.md | 1 + docs/rules/partial-become.md | 1 + docs/rules/playbook-extension.md | 1 + docs/rules/risky-file-permissions.md | 1 + docs/rules/risky-octal.md | 1 + docs/rules/risky-shell-pipe.md | 1 + docs/rules/role-name.md | 1 + docs/rules/run-once.md | 1 + docs/rules/sanity.md | 1 + docs/rules/schema.md | 1 + docs/rules/syntax-check.md | 1 + docs/rules/var-naming.md | 1 + docs/rules/warning.md | 1 + docs/rules/yaml.md | 1 + docs/stylesheets/extra.css | 174 ++++++++++++++++ docs/usage.md | 334 +++++++++++++++++++++++++++++++ 73 files changed, 1387 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/.nojekyll create mode 100644 docs/_static/ansible-lint.svg create mode 100644 docs/_static/images/ansible-lint-512.png create mode 100644 docs/_static/images/favicon.ico create mode 100644 docs/_static/images/logo_invert.png create mode 100644 docs/_static/theme_overrides.css create mode 100644 docs/configuring.md create mode 100644 docs/contributing.md create mode 100644 docs/custom-rules.md create mode 100644 docs/google04e29a42ae6e6cbc.html create mode 100644 docs/images/favicon.ico create mode 100644 docs/images/logo.png create mode 100644 docs/images/logo.svg create mode 100644 docs/index.md create mode 100644 docs/installing.md create mode 100644 docs/licenses/LICENSE.mit.txt create mode 100644 docs/philosophy.md create mode 100644 docs/pkg/.gitignore create mode 100644 docs/profiles.md create mode 100644 docs/redirects.yml create mode 120000 docs/rules/args.md create mode 120000 docs/rules/avoid-implicit.md create mode 120000 docs/rules/command-instead-of-module.md create mode 120000 docs/rules/command-instead-of-shell.md create mode 120000 docs/rules/deprecated-bare-vars.md create mode 120000 docs/rules/deprecated-local-action.md create mode 120000 docs/rules/deprecated-module.md create mode 120000 docs/rules/empty-string-compare.md create mode 120000 docs/rules/fqcn.md create mode 120000 docs/rules/galaxy.md create mode 120000 docs/rules/ignore-errors.md create mode 100644 docs/rules/index.md create mode 120000 docs/rules/inline-env-var.md create mode 120000 docs/rules/internal-error.md create mode 120000 docs/rules/jinja.md create mode 120000 docs/rules/key-order.md create mode 120000 docs/rules/latest.md create mode 120000 docs/rules/literal-compare.md create mode 120000 docs/rules/load-failure.md create mode 120000 docs/rules/loop-var-prefix.md create mode 120000 docs/rules/meta-incorrect.md create mode 120000 docs/rules/meta-no-tags.md create mode 120000 docs/rules/meta-runtime.md create mode 120000 docs/rules/meta-video-links.md create mode 120000 docs/rules/name.md create mode 120000 docs/rules/no-changed-when.md create mode 120000 docs/rules/no-free-form.md create mode 120000 docs/rules/no-handler.md create mode 120000 docs/rules/no-jinja-when.md create mode 120000 docs/rules/no-log-password.md create mode 120000 docs/rules/no-prompting.md create mode 120000 docs/rules/no-relative-paths.md create mode 120000 docs/rules/no-same-owner.md create mode 120000 docs/rules/no-tabs.md create mode 120000 docs/rules/only-builtins.md create mode 120000 docs/rules/package-latest.md create mode 120000 docs/rules/parser-error.md create mode 120000 docs/rules/partial-become.md create mode 120000 docs/rules/playbook-extension.md create mode 120000 docs/rules/risky-file-permissions.md create mode 120000 docs/rules/risky-octal.md create mode 120000 docs/rules/risky-shell-pipe.md create mode 120000 docs/rules/role-name.md create mode 120000 docs/rules/run-once.md create mode 120000 docs/rules/sanity.md create mode 120000 docs/rules/schema.md create mode 120000 docs/rules/syntax-check.md create mode 120000 docs/rules/var-naming.md create mode 120000 docs/rules/warning.md create mode 120000 docs/rules/yaml.md create mode 100644 docs/stylesheets/extra.css create mode 100644 docs/usage.md (limited to 'docs') diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..22695c6 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,16 @@ +# Old compiled python stuff +*.py[co] +# package building stuff +build +# Emacs backup files... +*~ +.\#* +.doctrees +# Generated docs stuff +ansible*.xml +.buildinfo +objects.inv +.doctrees +*.min.css +_build +rst_warnings diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/_static/ansible-lint.svg b/docs/_static/ansible-lint.svg new file mode 100644 index 0000000..eb6054a --- /dev/null +++ b/docs/_static/ansible-lint.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/_static/images/ansible-lint-512.png b/docs/_static/images/ansible-lint-512.png new file mode 100644 index 0000000..30ed574 Binary files /dev/null and b/docs/_static/images/ansible-lint-512.png differ diff --git a/docs/_static/images/favicon.ico b/docs/_static/images/favicon.ico new file mode 100644 index 0000000..23ad7da Binary files /dev/null and b/docs/_static/images/favicon.ico differ diff --git a/docs/_static/images/logo_invert.png b/docs/_static/images/logo_invert.png new file mode 100644 index 0000000..49e0897 Binary files /dev/null and b/docs/_static/images/logo_invert.png differ diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css new file mode 100644 index 0000000..b6b5d99 --- /dev/null +++ b/docs/_static/theme_overrides.css @@ -0,0 +1,24 @@ +/* table width fix via: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ + +/* override table width restrictions */ +@media screen and (min-width: 767px) { + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + * this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + +.icon-home { + display: none !important; +} + +/* Avoid using the red text for tt blocks */ +.rst-content code.literal, +.rst-content tt.literal { + color: #888888 !important; +} diff --git a/docs/configuring.md b/docs/configuring.md new file mode 100644 index 0000000..e67bbbc --- /dev/null +++ b/docs/configuring.md @@ -0,0 +1,73 @@ +# Configuration + +Customize how Ansible-lint runs against automation content to suit your needs. +You can ignore certain rules, enable `opt-in` rules, and control various other +settings. + +Ansible-lint loads configuration from a file in the current working directory or +from a file that you specify in the command line. If you provide configuration +on both via a config file and on the command line, list values are merged (for +example `exclude_paths`) and **True** is preferred for boolean values like +`quiet`. + +## Using local configuration files + +Specify Ansible-lint configuration in either `.ansible-lint`, +`.config/ansible-lint.yml`, or `.config/ansible-lint.yaml` in your current +working directory. + +!!! note + + If Ansible-lint cannot find a configuration file in the current directory it attempts to locate it in a parent directory. + However Ansible-lint does not try to load configuration that is outside the git repository. + +## Specifying configuration files + +Use the `-c ` CLI flag with command line invocations of Ansible-lint, +for example: + +```bash +ansible-lint -c path/to/ansible-lint-dev.yml +``` + +## Ansible-lint configuration + +The following values are supported, and function identically to their CLI +counterparts: + +```yaml +{!../.ansible-lint!} +``` + +## Ignoring rules for entire files + +Ansible-lint will load skip rules from an `.ansible-lint-ignore` or +`.config/ansible-lint-ignore.txt` file that should reside adjacent to the config +file. The file format is very simple, containing the filename and the rule to be +ignored. It also supports comments starting with `#`. + +```yaml title=".ansible-lint-ignore" +# this is just a comment +playbook.yml package-latest # disable package-latest rule for playbook.yml +playbook.yml deprecated-module +``` + +The file can also be created by adding `--generate-ignore` to the command line. +Keep in mind that this will override any existing file content. + +## Pre-commit setup + +To use Ansible-lint with [pre-commit], add the following to the +`.pre-commit-config.yaml` file in your local repository. + +Change **rev:** to either a commit sha or tag of Ansible-lint that contains +`.pre-commit-hooks.yaml`. + +```yaml +- repo: https://github.com/ansible/ansible-lint + rev: ... # put latest release tag from https://github.com/ansible/ansible-lint/releases/ + hooks: + - id: ansible-lint +``` + +[pre-commit]: https://pre-commit.com/ diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..3e8e41d --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,119 @@ +# Contributing to Ansible-lint + +To contribute to ansible-lint, please use pull requests on a branch of your own +fork. + +After [creating your fork on GitHub], you can do: + +```shell-session +$ git clone --recursive git@github.com:your-name/ansible-lint +$ cd ansible-lint +$ git checkout -b your-branch-name +# DO SOME CODING HERE +$ git add your new files +$ git commit -v +$ git push origin your-branch-name +``` + +You will then be able to create a pull request from your commit. + +All fixes to core functionality (i.e. anything except docs or examples) should +be accompanied by tests that fail prior to your change and succeed afterwards. + +Feel free to raise issues in the repo if you feel unable to contribute a code +fix. + +## Standards + +ansible-lint works only with supported Ansible versions at the time it was +released. + +Automated tests will be run against all PRs, to run checks locally before +pushing commits, just use [tox](https://tox.wiki/en/latest/). + +% DO-NOT-REMOVE-deps-snippet-PLACEHOLDER + +## Talk to us + +Use Github [discussions] forum or for a live chat experience try +`#ansible-devtools` IRC channel on libera.chat or Matrix room +[#devtools:ansible.com](https://matrix.to/#/#devtools:ansible.com). + +For the full list of Ansible IRC and Mailing list, please see the [Ansible +Communication] page. Release announcements will be made to the [Ansible +Announce] list. + +Possible security bugs should be reported via email to +. + +## Code of Conduct + +As with all Ansible projects, we have a [Code of Conduct]. + +[ansible announce]: https://groups.google.com/forum/#!forum/ansible-announce +[ansible communication]: + https://docs.ansible.com/ansible/latest/community/communication.html +[code of conduct]: + https://docs.ansible.com/ansible/latest/community/code_of_conduct.html +[creating your fork on github]: + https://docs.github.com/en/get-started/quickstart/contributing-to-projects +[discussions]: https://github.com/ansible/ansible-lint/discussions +[supported ansible versions]: + https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-release-cycle +[tox]: https://tox.readthedocs.io + +## Module dependency graph + +Extra care should be taken when considering adding any dependency. Removing most +dependencies on Ansible internals is desired as these can change without any +warning. + +```bash exec="1" source="console" +_PIP_USE_IMPORTLIB_METADATA=0 pipdeptree -p ansible-lint +``` + +## Adding a new rule + +Writing a new rule is as easy as adding a single new rule, one that combines +**implementation, testing and documentation**. + +One good example is [MetaTagValidRule] which can easily be copied in order to +create a new rule by following the steps below: + +- Use a short but clear class name, which must match the filename +- Pick an unused `id`, the first number is used to determine rule section. Look + at [rules](rules/index.md) page and pick one that matches the best your new + rule and ee which one fits best. +- Include `experimental` tag. Any new rule must stay as experimental for at + least two weeks until this tag is removed in next major release. +- Update all class level variables. +- Implement linting methods needed by your rule, these are those starting with + **match** prefix. Implement only those you need. For the moment you will need + to look at how similar rules were implemented to figure out what to do. +- Update the tests. It must have at least one test and likely also a negative + match one. +- If the rule is task specific, it may be best to include a test to verify its + use inside blocks as well. +- Optionally run only the rule specific tests with a command like: + {command}`tox -e py -- -k NewRule` +- Run {command}`tox` in order to run all ansible-lint tests. Adding a new rule + can break some other tests. Update them if needed. +- Run {command}`ansible-lint -L` and check that the rule description renders + correctly. +- Build the docs using {command}`tox -e docs` and check that the new rule is + displayed correctly in them. + +[metatagvalidrule]: + https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/rules/meta_no_tags.py + +## Documentation changes + +To build the docs, run `tox -e docs`. At the end of the build, you will see the +local location of your built docs. + +Building docs locally may not be identical to CI/CD builds. We recommend you to +create a draft PR and check the RTD PR preview page too. + +If you do not want to learn the reStructuredText format, you can also +[file an issue](https://github.com/ansible/ansible-lint/issues), and let us know +how we can improve our documentation. diff --git a/docs/custom-rules.md b/docs/custom-rules.md new file mode 100644 index 0000000..e821a77 --- /dev/null +++ b/docs/custom-rules.md @@ -0,0 +1,112 @@ +# Custom linting rules + +Define and use your own sets of rules with Ansible-lint. + +## Rule definitions + +You define each custom rule in a unique Python class file. Default rules are +named _DeprecatedVariableRule.py_, etc. + +Each rule should have a short description as a Python docstring wrapped in +triple quotes `"""` immediately after the class name. The short description +should be brief and meaningfully explain the purpose of the rule to users. + +Each rule definition should have the following parts: + +- `id` provides a unique identifier to the rule. +- `description` explains what the rule checks for. +- `tags` specifies one or more tags for including or excluding the rule. + +### Match and matchtask methods + +Each rule definition should also invoke one of the following methods: + +- `match` takes a line and returns: + - None or False if the line does not match the test. + - True or a custom message if the line does match the test. (This allows one + rule to test multiple behaviors - see e.g. the + _CommandsInsteadOfModulesRule_.) +- `matchtask` operates on a single task or handler, such that tasks get + standardized to always contain a _module_ key and _module_arguments_ key. + Other common task modifiers, such as _when_, _with_items_, etc., are also + available as keys if present in the task. + +The following is an example rule that uses the `match` method: + +```python +from ansiblelint.rules import AnsibleLintRule + +class DeprecatedVariableRule(AnsibleLintRule): + """Deprecated variable declarations.""" + + id = 'EXAMPLE002' + description = 'Check for lines that have old style ${var} ' + \ + 'declarations' + tags = { 'deprecations' } + + def match(self, line: str) -> Union[bool, str]: + return '${' in line +``` + +The following is an example rule that uses the `matchtask` method: + +```python +from typing import TYPE_CHECKING, Any, Dict, Union + +import ansiblelint.utils +from ansiblelint.rules import AnsibleLintRule + +if TYPE_CHECKING: + from ansiblelint.file_utils import Lintable + from ansiblelint.utils import Task + +class TaskHasTag(AnsibleLintRule): + """Tasks must have tag.""" + + id = 'EXAMPLE001' + description = 'Tasks must have tag' + tags = ['productivity'] + + def matchtask(self, task: Task, file: 'Lintable' | None = None) -> Union[bool,str]: + # If the task include another task or make the playbook fail + # Don't force to have a tag + if not set(task.keys()).isdisjoint(['include','fail']): + return False + + # Task should have tags + if not task.has_key('tags'): + return True + + return False +``` + +The task argument to `matchtask` contains a number of keys - the critical one is +_action_. The value of `task['action']` contains the module being used, and the +arguments passed, both as key-value pairs and a list of other arguments (e.g. +the command used with shell). + +## Packaging custom rules + +Ansible-lint automatically loads and enables custom rules in Python packages +from the _custom_ subdirectory. This subdirectory is part of the Ansible-lint +installation directory, for example: + +`/usr/lib/python3.8/site-packages/ansiblelint/rules/custom/` + +To automatically load custom rules, do the following: + +1. Package your custom rules as a Python package with a descriptive name. + +2. Configure the \[options\] section of the `setup.cfg` of your custom rules + Python package as in the following example: + + ```yaml + [options] + packages = + ansiblelint.rules.custom. + package_dir = + ansiblelint.rules.custom. = + ``` + +3. Install the Python package into + `/custom//`. diff --git a/docs/google04e29a42ae6e6cbc.html b/docs/google04e29a42ae6e6cbc.html new file mode 100644 index 0000000..0b663fa --- /dev/null +++ b/docs/google04e29a42ae6e6cbc.html @@ -0,0 +1 @@ +google-site-verification: google04e29a42ae6e6cbc.html diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000..ea4ebc1 Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000..f3626b0 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..ffe210b --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..df877c6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,28 @@ +# Ansible Lint Documentation + +## About Ansible Lint + +Ansible Lint is a command-line tool for linting **playbooks, roles and +collections** aimed toward any Ansible users. Its main goal is to promote proven +practices, patterns and behaviors while avoiding common pitfalls that can easily +lead to bugs or make code harder to maintain. + +Ansible lint is also supposed to help users upgrade their code to work with +newer versions of Ansible. Due to this reason we recommend using it with the +newest version of Ansible, even if the version used in production may be older. + +As any other linter, it is opinionated. Still, its rules are the result of +community contributions and they can always be disabled based individually or by +category by each user. + +[Ansible Galaxy project](https://github.com/ansible/galaxy/) makes use of this +linter to compute quality scores for [Galaxy Hub](https://galaxy.ansible.com/) +contributed content. This does not mean this tool only targets those that want +to share their code. Files like `galaxy.yml`, or sections like `galaxy_info` +inside `meta.yml` help with documentation and maintenance, even for unpublished +roles or collections. + +The project was originally started by +[@willthames](https://github.com/willthames/) and has since been adopted by the +Ansible Community team. Its development is purely community driven while keeping +permanent communications with other Ansible teams. diff --git a/docs/installing.md b/docs/installing.md new file mode 100644 index 0000000..6008de7 --- /dev/null +++ b/docs/installing.md @@ -0,0 +1,113 @@ +# Installing + +Install Ansible-lint to apply rules and follow best practices with your +automation content. + +!!! note + + Ansible-lint does not currently support installation on Windows systems. + +!!! warning + + Ansible-lint does not support any installation methods that are not mentioned in + this document. Before raising any bugs related to installation, review all of + the following details: + + - You should use installation methods outlined in this document only. + - You should upgrade the Python installer (`pip` or `pipx`) to the latest + version available from pypi.org. If you used a system package manager, you + will need to upgrade the installer to a newer version. + - If you are installing from a git zip archive, which is not supported but + should work, ensure you use the main branch and the latest version of pip and + setuptools. + - If you are installing Ansible-lint within a container or system package, you + should not report the issue here. Contact the relevant container or package + provider instead. + - If you are using [poetry](https://python-poetry.org/), read this + [discussion](https://github.com/ansible/ansible-lint/discussions/2820#discussioncomment-4400380). + + Pull requests to improve installation instructions are welcome. Any new issues + related to installation will be closed and locked. + +For a container image, we recommend using +[creator-ee](https://github.com/ansible/creator-ee/), which includes +Ansible-lint. If you have a use case that the `creator-ee` container doesn't +satisfy, please contact the team through the +[discussions](https://github.com/ansible/ansible-lint/discussions) forum. + +You can also run Ansible-lint on your source code with the +[Ansible-lint GitHub action](https://github.com/marketplace/actions/ansible-lint) +instead of installing it directly. + +## Installing the latest version + +You can install the most recent version of Ansible-lint with the [pip3] or +[pipx] Python package manager. Use [pipx] to isolate Ansible-lint from your +current Python environment as an alternative to creating a virtual environment. + +```bash +# This also installs ansible-core if it is not already installed +pip3 install ansible-lint +``` + +## Installing on Fedora and RHEL + +You can install Ansible-lint on Fedora, or Red Hat Enterprise Linux (RHEL) with +the `dnf` package manager. + +```bash +dnf install ansible-lint +``` + +!!! note + + On RHEL, `ansible-lint` package is part of "Red Hat Ansible Automation + Platform" subscription, which needs to be activated. + +## Installing from source code + +**Note**: `pip>=22.3.1` is required for installation from the source repository. +Please consult the [PyPA User Guide] to learn more about managing Pip versions. + +```bash +pip3 install git+https://github.com/ansible/ansible-lint +``` + +[installing_from_source]: https://pypi.org/project/pip/ +[pip3]: https://pypi.org/project/pip/ +[pipx]: https://pypa.github.io/pipx/ +[pypa user guide]: + https://packaging.python.org/en/latest/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date + +## Installing Ansible Lint as a GitHub Action + +To use the action simply create a file `.github/workflows/ansible-lint.yml` with +content similar to the example below: + +```yaml +# .github/workflows/ansible-lint.yml +name: ansible-lint +on: + pull_request: + branches: ["stable", "release/v*"] +jobs: + build: + name: Ansible Lint # Naming the build is important to use it as a status check + runs-on: ubuntu-latest + steps: + - name: Run ansible-lint + uses: ansible/ansible-lint@v6 +``` + +Due to limitations on how GitHub Actions are processing arguments, we do not +plan to provide extra options. You will have to make use of +[ansible-lint own configuration file](https://ansible-lint.readthedocs.io/configuring/) +for altering its behavior. + +To also enable [dependabot][dependabot] automatic updates the newer versions of +ansible-lint action you should create a file similar to +[.github/dependabot.yml][.github/dependabot.yml] + +[dependabot]: https://docs.github.com/en/code-security/dependabot +[.github/dependabot.yml]: + https://github.com/ansible/ansible-lint/blob/main/.github/dependabot.yml#L13-L19 diff --git a/docs/licenses/LICENSE.mit.txt b/docs/licenses/LICENSE.mit.txt new file mode 100644 index 0000000..4b48ba2 --- /dev/null +++ b/docs/licenses/LICENSE.mit.txt @@ -0,0 +1,21 @@ +Copyright (c) 2013-2018 Will Thames +Copyright (c) 2018 Ansible by Red Hat + + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/docs/philosophy.md b/docs/philosophy.md new file mode 100644 index 0000000..2ef698d --- /dev/null +++ b/docs/philosophy.md @@ -0,0 +1,109 @@ +# Philosophy of ansible-lint + +Ansible **playbooks, roles, and collections** should read like documentation, be +production ready, unambiguous, and provide consistent results. + +`Ansible-lint` should be considered a trusted advisor, helping ansible content +creators write and package high-quality Ansible content. While not all rules may +be applicable in all situations, they should be followed whenever possible. + +The goal of `ansible-lint` is to ensure that content created by different people +has a similar look and feel. This makes the adoption and use of Ansible content +easier in the community and enterprise. By keeping the number of configurable +features at a minimum, consistent outcomes between authors can be achieved. + +## History and the future + +`ansible-lint` is almost a decade old, and its current list of rules is the +result of a collaboration between many people. The tool originated as a +community project and is currently part of the Ansible Galaxy submission and +validation process. + +In the future, it will be an official component of the Red Hat Ansible +Automation Platform, used during the collections certification process and the +recommended Ansible content linter for Red Hat customers. + +Starting in 2022, additional rules will be added that help content creators +ready their content for production use. It will be through the use of +ansible-lint and these rules, developers can have confidence their playbooks, +roles, and task files are easy to understand and produce consistent results when +run against anything, from servers in a home lab to mission-critical systems in +the cloud. + +## Style and formatting + +The focus of Ansible content creators should be on automation, outcomes and +readability, rather than style or formatting. This is why we follow the same +concepts as other code formatting tools like +[black](https://github.com/psf/black) and [prettier](https://prettier.io/). + +Adoption of `ansible-lint` will save time by keeping reviews focused on the +quality of the content and less so on the nuances of formatting and style. + +As code formatting is not an art, we can save your project time and effort by +applying a standardized code style and formatting. + +## Q&A + +### Why does ansible-lint not accept all valid ansible syntax? + +`ansible-core` continues to mature while maintaining backward compatibility with +early versions. `ansible-lint` has never intended to support the whole +historical Ansible language syntax variations, but instead only the best of it. + +It supports a broad vocabulary of keywords and styles. Over time, changes in the +language have led to an improved experience for authors and consumers of Ansible +content. The rules in `ansible-lint` suggest the use of these patterns. + +It is these usage patterns that are written as rules in `ansible-lint`, leading +to improved readability of **playbooks, roles**, and **collections**. The linter +will always be more restrictive and opinionated regarding what it accepts. It is +part of its design. We are not forced to keep the same backward compatibility +level as Ansible, so we can tell people to avoid specific syntax for various +reasons, such as being deprecated, unsafe, or hard to maintain. + +Based on the extensive history of `ansible-lint` and user feedback, it notifies +you about discouraged practices, sometimes before `ansible-core` starts doing +so. + +### What if I do not agree with a specific rule? + +We recognize that some projects will find at least one rule that might not suit +their needs. Use the `skip_list` feature to temporarily bypass that rule until +you have time to update your Ansible content. + +### Who decides which best practices get adopted in ansible-lint? + +The main source of new ideas was and remains our community. Before proposing a +change, check with a few other Ansible users that work on different projects and +see if they find it useful or not. + +It is better to get enough relevant feedback on our discussion forum before +starting to implement new rules. If the proposed rule appears popular and does +not conflict with existing rules, a core (maintainer) will tell you that the +proposed rule can be added to ansible-lint, so you can start working on it +without fear of rejection. + +The core team will decide on how a new rule will be added. Usually, they are +added as experimental (warnings only) or even as opt-ins, being made implicit +only when a major version is released. + +### Do I need to pass all rules to get my collection certified? + +Not really. The certification process is likely to use only a subset of rules. +At this time, we are working on building that list. + +### Why lots of official Ansible docs examples are not passing linting? + +Most of the official examples are written to exemplify specific features, and +some might conflict with our rules. Still, we plan to include linting of +official examples in the future and add specific exclusions where needed, making +it more likely that a copy/paste from the docs will not raise a bunch of linter +violations. + +### Why does ansible-lint require an Ansible version newer than what I use in production? + +Use `ansible-lint` as a **static analysis** tool for your content. You can run +it with a version of ansible that is different than what you use in production. +This helps you prepare your content for the future, so don't be afraid of using +it in such a way. diff --git a/docs/pkg/.gitignore b/docs/pkg/.gitignore new file mode 100644 index 0000000..d6b7ef3 --- /dev/null +++ b/docs/pkg/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore diff --git a/docs/profiles.md b/docs/profiles.md new file mode 100644 index 0000000..7208376 --- /dev/null +++ b/docs/profiles.md @@ -0,0 +1,110 @@ + + +# Profiles + +Ansible-lint profiles gradually increase the strictness of rules as your Ansible +content lifecycle. To configure linter to use a specific profile, read +[applying-profiles][]. + +!!! note + + Rules with `*` in the suffix are not yet implemented but are documented with linked GitHub issues. + +## min + +The `min` profile ensures that Ansible can load content. Rules in this profile +are mandatory because they prevent fatal errors. You can add files to the +exclude list or provide dependencies to load the correct files. + +- [internal-error](rules/internal-error.md) +- [load-failure](rules/load-failure.md) +- [parser-error](rules/parser-error.md) +- [syntax-check](rules/syntax-check.md) + +## basic + +The `basic` profile prevents common coding issues and enforces standard styles +and formatting. It extends [min](#min) profile. + +- [command-instead-of-module](rules/command-instead-of-module.md) +- [command-instead-of-shell](rules/command-instead-of-shell.md) +- [deprecated-bare-vars](rules/deprecated-bare-vars.md) +- [deprecated-local-action](rules/deprecated-local-action.md) +- [deprecated-module](rules/deprecated-module.md) +- [inline-env-var](rules/inline-env-var.md) +- [key-order](rules/key-order.md) +- [literal-compare](rules/literal-compare.md) +- [jinja](rules/jinja.md) +- [no-free-form](https://github.com/ansible/ansible-lint/issues/2117) +- [no-jinja-when](rules/no-jinja-when.md) +- [no-tabs](rules/no-tabs.md) +- [partial-become](rules/partial-become.md) +- [playbook-extension](rules/playbook-extension.md) +- [role-name](rules/role-name.md) +- [schema](rules/schema.md) +- [name](rules/name.md) +- [var-naming](rules/var-naming.md) +- [yaml](rules/yaml.md) + +## moderate + +The `moderate` profile ensures that content adheres to best practices for making +content easier to read and maintain. It extends [basic](#basic) profile. + +- [name[template]](rules/name.md) +- [name[imperative]](https://github.com/ansible/ansible-lint/issues/2170) +- [name[casing]](rules/name.md) +- [spell-var-name](https://github.com/ansible/ansible-lint/issues/2168) + +## safety + +The `safety` profile avoids module calls that can have non-determinant outcomes +or security concerns. It extends [moderate](#moderate) profile. + +- [avoid-implicit](rules/avoid-implicit.md) +- [latest](rules/latest.md) +- [package-latest](rules/package-latest.md) +- [risky-file-permissions](rules/risky-file-permissions.md) +- [risky-octal](rules/risky-octal.md) +- [risky-shell-pipe](rules/risky-shell-pipe.md) + +## shared + +The `shared` profile ensures that content follows best practices for packaging +and publishing. This profile is intended for content creators who want to make +Ansible playbooks, roles, or collections available from +[galaxy.ansible.com](https://galaxy.ansible.com/), +[automation-hub](https://console.redhat.com/ansible/automation-hub), or a +private instance. It extends [safety](#safety) profile. + +- [galaxy](rules/galaxy.md) +- [ignore-errors](rules/ignore-errors.md) +- [layout](https://github.com/ansible/ansible-lint/issues/1900) +- [meta-incorrect](rules/meta-incorrect.md) +- [meta-no-tags](rules/meta-no-tags.md) +- [meta-video-links](rules/meta-video-links.md) +- [meta-version](https://github.com/ansible/ansible-lint/issues/2103) +- [meta-runtime](rules/meta-runtime.md) +- [no-changed-when](rules/no-changed-when.md) +- [no-handler](rules/no-handler.md) +- [no-relative-paths](rules/no-relative-paths.md) +- [max-block-depth](https://github.com/ansible/ansible-lint/issues/2173) +- [max-tasks](https://github.com/ansible/ansible-lint/issues/2172) +- [unsafe-loop](https://github.com/ansible/ansible-lint/issues/2038) + +## production + +The `production` profile ensures that content meets requirements for inclusion +in +[Ansible Automation Platform (AAP)](https://www.redhat.com/en/technologies/management/ansible) +as validated or certified content. It extends [shared](#shared) profile. + +- [avoid-dot-notation](https://github.com/ansible/ansible-lint/issues/2174) +- [sanity](https://github.com/ansible/ansible-lint/issues/2121) +- [fqcn](rules/fqcn.md) +- [import-task-no-when](https://github.com/ansible/ansible-lint/issues/2219) +- [meta-no-dependencies](https://github.com/ansible/ansible-lint/issues/2159) +- [single-entry-point](https://github.com/ansible/ansible-lint/issues/2242) +- [use-loop](https://github.com/ansible/ansible-lint/issues/2204) diff --git a/docs/redirects.yml b/docs/redirects.yml new file mode 100644 index 0000000..7077813 --- /dev/null +++ b/docs/redirects.yml @@ -0,0 +1,38 @@ +# Authoritative list of redirects we have configured in RTD, +# https://pypi.org/project/readthedocs-cli/ +--- +- type: page + from_url: /rules/git-latest/ + to_url: /rules/latest/ +- type: page + from_url: /rules/hg-latest/ + to_url: /rules/latest/ +- type: page + from_url: /rules/meta-no-info/ + # cspell:disable-next-line + to_url: /rules/schemas/#schemameta +- type: page + from_url: /rules/deprecated-command-syntax/ + to_url: /rules/no-free-form/ +- type: page + from_url: /default_rules/index/ + to_url: /rules/ +- type: page + from_url: /en/latest/ + to_url: / +- type: page + from_url: /en/latest/installing.html + to_url: /installing/ +- type: page + from_url: /en/latest/rules.html + to_url: /rules/ +- type: page + from_url: /en/latest/default_rules/ + to_url: /rules/ +- type: page + from_url: /en/latest/pkg/ansiblelint.rules.empty_string_compare/ + to_url: /rules/empty-string-compare/ +# Keep this last or it will match all the other rules +- type: sphinx_htmldir + from_url: "" + to_url: "" diff --git a/docs/rules/args.md b/docs/rules/args.md new file mode 120000 index 0000000..194c2d3 --- /dev/null +++ b/docs/rules/args.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/args.md \ No newline at end of file diff --git a/docs/rules/avoid-implicit.md b/docs/rules/avoid-implicit.md new file mode 120000 index 0000000..4ddfc82 --- /dev/null +++ b/docs/rules/avoid-implicit.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/avoid_implicit.md \ No newline at end of file diff --git a/docs/rules/command-instead-of-module.md b/docs/rules/command-instead-of-module.md new file mode 120000 index 0000000..9f6809d --- /dev/null +++ b/docs/rules/command-instead-of-module.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/command_instead_of_module.md \ No newline at end of file diff --git a/docs/rules/command-instead-of-shell.md b/docs/rules/command-instead-of-shell.md new file mode 120000 index 0000000..2bf0747 --- /dev/null +++ b/docs/rules/command-instead-of-shell.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/command_instead_of_shell.md \ No newline at end of file diff --git a/docs/rules/deprecated-bare-vars.md b/docs/rules/deprecated-bare-vars.md new file mode 120000 index 0000000..80ca8f7 --- /dev/null +++ b/docs/rules/deprecated-bare-vars.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/deprecated_bare_vars.md \ No newline at end of file diff --git a/docs/rules/deprecated-local-action.md b/docs/rules/deprecated-local-action.md new file mode 120000 index 0000000..fd44cd8 --- /dev/null +++ b/docs/rules/deprecated-local-action.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/deprecated_local_action.md \ No newline at end of file diff --git a/docs/rules/deprecated-module.md b/docs/rules/deprecated-module.md new file mode 120000 index 0000000..28dfe7f --- /dev/null +++ b/docs/rules/deprecated-module.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/deprecated_module.md \ No newline at end of file diff --git a/docs/rules/empty-string-compare.md b/docs/rules/empty-string-compare.md new file mode 120000 index 0000000..3470d52 --- /dev/null +++ b/docs/rules/empty-string-compare.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/empty_string_compare.md \ No newline at end of file diff --git a/docs/rules/fqcn.md b/docs/rules/fqcn.md new file mode 120000 index 0000000..5623fae --- /dev/null +++ b/docs/rules/fqcn.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/fqcn.md \ No newline at end of file diff --git a/docs/rules/galaxy.md b/docs/rules/galaxy.md new file mode 120000 index 0000000..02cebd0 --- /dev/null +++ b/docs/rules/galaxy.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/galaxy.md \ No newline at end of file diff --git a/docs/rules/ignore-errors.md b/docs/rules/ignore-errors.md new file mode 120000 index 0000000..ea5578d --- /dev/null +++ b/docs/rules/ignore-errors.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/ignore_errors.md \ No newline at end of file diff --git a/docs/rules/index.md b/docs/rules/index.md new file mode 100644 index 0000000..4f4dc3d --- /dev/null +++ b/docs/rules/index.md @@ -0,0 +1,51 @@ +# Rules + +- [args][] +- [avoid-implicit][] +- [command-instead-of-module][] +- [command-instead-of-shell][] +- [deprecated-bare-vars][] +- [deprecated-local-action][] +- [deprecated-module][] +- [empty-string-compare][] +- [fqcn][] +- [galaxy][] +- [ignore-errors][] +- [inline-env-var][] +- [internal-error][] +- [jinja][] +- [key-order][] +- [latest][] +- [literal-compare][] +- [load-failure][] +- [loop-var-prefix][] +- [meta-incorrect][] +- [meta-no-tags][] +- [meta-runtime][] +- [meta-video-links][] +- [name][] +- [no-changed-when][] +- [no-free-form][] +- [no-handler][] +- [no-jinja-when][] +- [no-log-password][] +- [no-prompting][] +- [no-relative-paths][] +- [no-same-owner][] +- [no-tabs][] +- [only-builtins][] +- [package-latest][] +- [parser-error][] +- [partial-become][] +- [playbook-extension][] +- [risky-file-permissions][] +- [risky-octal][] +- [risky-shell-pipe][] +- [role-name][] +- [run-once][] +- [sanity][] +- [schema][] +- [syntax-check][] +- [var-naming][] +- [warning][] +- [yaml][] diff --git a/docs/rules/inline-env-var.md b/docs/rules/inline-env-var.md new file mode 120000 index 0000000..8942b5c --- /dev/null +++ b/docs/rules/inline-env-var.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/inline_env_var.md \ No newline at end of file diff --git a/docs/rules/internal-error.md b/docs/rules/internal-error.md new file mode 120000 index 0000000..8287685 --- /dev/null +++ b/docs/rules/internal-error.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/internal_error.md \ No newline at end of file diff --git a/docs/rules/jinja.md b/docs/rules/jinja.md new file mode 120000 index 0000000..6f5fc6e --- /dev/null +++ b/docs/rules/jinja.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/jinja.md \ No newline at end of file diff --git a/docs/rules/key-order.md b/docs/rules/key-order.md new file mode 120000 index 0000000..929faa6 --- /dev/null +++ b/docs/rules/key-order.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/key_order.md \ No newline at end of file diff --git a/docs/rules/latest.md b/docs/rules/latest.md new file mode 120000 index 0000000..6280f1a --- /dev/null +++ b/docs/rules/latest.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/latest.md \ No newline at end of file diff --git a/docs/rules/literal-compare.md b/docs/rules/literal-compare.md new file mode 120000 index 0000000..4a7ab23 --- /dev/null +++ b/docs/rules/literal-compare.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/literal_compare.md \ No newline at end of file diff --git a/docs/rules/load-failure.md b/docs/rules/load-failure.md new file mode 120000 index 0000000..38a66a6 --- /dev/null +++ b/docs/rules/load-failure.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/load-failure.md \ No newline at end of file diff --git a/docs/rules/loop-var-prefix.md b/docs/rules/loop-var-prefix.md new file mode 120000 index 0000000..6cebf6a --- /dev/null +++ b/docs/rules/loop-var-prefix.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/loop_var_prefix.md \ No newline at end of file diff --git a/docs/rules/meta-incorrect.md b/docs/rules/meta-incorrect.md new file mode 120000 index 0000000..34c1891 --- /dev/null +++ b/docs/rules/meta-incorrect.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_incorrect.md \ No newline at end of file diff --git a/docs/rules/meta-no-tags.md b/docs/rules/meta-no-tags.md new file mode 120000 index 0000000..b103c57 --- /dev/null +++ b/docs/rules/meta-no-tags.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_no_tags.md \ No newline at end of file diff --git a/docs/rules/meta-runtime.md b/docs/rules/meta-runtime.md new file mode 120000 index 0000000..82db95a --- /dev/null +++ b/docs/rules/meta-runtime.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_runtime.md \ No newline at end of file diff --git a/docs/rules/meta-video-links.md b/docs/rules/meta-video-links.md new file mode 120000 index 0000000..176559d --- /dev/null +++ b/docs/rules/meta-video-links.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_video_links.md \ No newline at end of file diff --git a/docs/rules/name.md b/docs/rules/name.md new file mode 120000 index 0000000..213f924 --- /dev/null +++ b/docs/rules/name.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/name.md \ No newline at end of file diff --git a/docs/rules/no-changed-when.md b/docs/rules/no-changed-when.md new file mode 120000 index 0000000..e821c77 --- /dev/null +++ b/docs/rules/no-changed-when.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_changed_when.md \ No newline at end of file diff --git a/docs/rules/no-free-form.md b/docs/rules/no-free-form.md new file mode 120000 index 0000000..ee80943 --- /dev/null +++ b/docs/rules/no-free-form.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_free_form.md \ No newline at end of file diff --git a/docs/rules/no-handler.md b/docs/rules/no-handler.md new file mode 120000 index 0000000..1b690c6 --- /dev/null +++ b/docs/rules/no-handler.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_handler.md \ No newline at end of file diff --git a/docs/rules/no-jinja-when.md b/docs/rules/no-jinja-when.md new file mode 120000 index 0000000..d2f9453 --- /dev/null +++ b/docs/rules/no-jinja-when.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_jinja_when.md \ No newline at end of file diff --git a/docs/rules/no-log-password.md b/docs/rules/no-log-password.md new file mode 120000 index 0000000..ac5e869 --- /dev/null +++ b/docs/rules/no-log-password.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_log_password.md \ No newline at end of file diff --git a/docs/rules/no-prompting.md b/docs/rules/no-prompting.md new file mode 120000 index 0000000..49b3d4b --- /dev/null +++ b/docs/rules/no-prompting.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_prompting.md \ No newline at end of file diff --git a/docs/rules/no-relative-paths.md b/docs/rules/no-relative-paths.md new file mode 120000 index 0000000..6fc7d42 --- /dev/null +++ b/docs/rules/no-relative-paths.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_relative_paths.md \ No newline at end of file diff --git a/docs/rules/no-same-owner.md b/docs/rules/no-same-owner.md new file mode 120000 index 0000000..6367a7a --- /dev/null +++ b/docs/rules/no-same-owner.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_same_owner.md \ No newline at end of file diff --git a/docs/rules/no-tabs.md b/docs/rules/no-tabs.md new file mode 120000 index 0000000..d938e62 --- /dev/null +++ b/docs/rules/no-tabs.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_tabs.md \ No newline at end of file diff --git a/docs/rules/only-builtins.md b/docs/rules/only-builtins.md new file mode 120000 index 0000000..7fa5e7a --- /dev/null +++ b/docs/rules/only-builtins.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/only_builtins.md \ No newline at end of file diff --git a/docs/rules/package-latest.md b/docs/rules/package-latest.md new file mode 120000 index 0000000..18d6723 --- /dev/null +++ b/docs/rules/package-latest.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/package_latest.md \ No newline at end of file diff --git a/docs/rules/parser-error.md b/docs/rules/parser-error.md new file mode 120000 index 0000000..954422f --- /dev/null +++ b/docs/rules/parser-error.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/parser-error.md \ No newline at end of file diff --git a/docs/rules/partial-become.md b/docs/rules/partial-become.md new file mode 120000 index 0000000..f57aa23 --- /dev/null +++ b/docs/rules/partial-become.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/partial_become.md \ No newline at end of file diff --git a/docs/rules/playbook-extension.md b/docs/rules/playbook-extension.md new file mode 120000 index 0000000..429aa2f --- /dev/null +++ b/docs/rules/playbook-extension.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/playbook_extension.md \ No newline at end of file diff --git a/docs/rules/risky-file-permissions.md b/docs/rules/risky-file-permissions.md new file mode 120000 index 0000000..a6718bf --- /dev/null +++ b/docs/rules/risky-file-permissions.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/risky_file_permissions.md \ No newline at end of file diff --git a/docs/rules/risky-octal.md b/docs/rules/risky-octal.md new file mode 120000 index 0000000..dffaad5 --- /dev/null +++ b/docs/rules/risky-octal.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/risky_octal.md \ No newline at end of file diff --git a/docs/rules/risky-shell-pipe.md b/docs/rules/risky-shell-pipe.md new file mode 120000 index 0000000..444efa2 --- /dev/null +++ b/docs/rules/risky-shell-pipe.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/risky_shell_pipe.md \ No newline at end of file diff --git a/docs/rules/role-name.md b/docs/rules/role-name.md new file mode 120000 index 0000000..e050ccd --- /dev/null +++ b/docs/rules/role-name.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/role_name.md \ No newline at end of file diff --git a/docs/rules/run-once.md b/docs/rules/run-once.md new file mode 120000 index 0000000..b238e25 --- /dev/null +++ b/docs/rules/run-once.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/run_once.md \ No newline at end of file diff --git a/docs/rules/sanity.md b/docs/rules/sanity.md new file mode 120000 index 0000000..71346b4 --- /dev/null +++ b/docs/rules/sanity.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/sanity.md \ No newline at end of file diff --git a/docs/rules/schema.md b/docs/rules/schema.md new file mode 120000 index 0000000..a278289 --- /dev/null +++ b/docs/rules/schema.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/schema.md \ No newline at end of file diff --git a/docs/rules/syntax-check.md b/docs/rules/syntax-check.md new file mode 120000 index 0000000..0e5e8f1 --- /dev/null +++ b/docs/rules/syntax-check.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/syntax_check.md \ No newline at end of file diff --git a/docs/rules/var-naming.md b/docs/rules/var-naming.md new file mode 120000 index 0000000..50bc37b --- /dev/null +++ b/docs/rules/var-naming.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/var_naming.md \ No newline at end of file diff --git a/docs/rules/warning.md b/docs/rules/warning.md new file mode 120000 index 0000000..9944a53 --- /dev/null +++ b/docs/rules/warning.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/warning.md \ No newline at end of file diff --git a/docs/rules/yaml.md b/docs/rules/yaml.md new file mode 120000 index 0000000..b033a46 --- /dev/null +++ b/docs/rules/yaml.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/yaml.md \ No newline at end of file diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..9b14d83 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,174 @@ +/* +Inspired by https://spec.draculatheme.com/ specification +*/ +:root { + --ansi-red: #ff5555; + --ansi-green: #50fa7b; + --ansi-blue: #265285; + --ansi-yellow: #ffb86c; /* Orange */ + --ansi-magenta: #bd93f9; /* Purple */ + --ansi-cyan: #8be9fd; + --ansi-black: #282a36; + --ansi-white: #f8f8f2; +} + +.-Color-Green, +.-Color-Faint-Green, +.-Color-Bold-Green { + color: var(--ansi-green); +} +.-Color-Red, +.-Color-Faint-Red, +.-Color-Bold-Red { + color: var(--ansi-red); +} +.-Color-Yellow, +.-Color-Faint-Yellow, +.-Color-Bold-Yellow { + color: var(--ansi-yellow); +} +.-Color-Blue, +.-Color-Faint-Blue, +.-Color-Bold-Blue { + color: var(--ansi-blue); +} +.-Color-Magenta, +.-Color-Faint-Magenta, +.-Color-Bold-Magenta { + color: var(--ansi-magenta); +} +.-Color-Cyan, +.-Color-Faint-Cyan, +.-Color-Bold-Cyan { + color: var(--ansi-cyan); +} +.-Color-White, +.-Color-Faint-White, +.-Color-Bold-White { + color: var(--ansi-white); +} +.-Color-Black, +.-Color-Faint-Black, +.-Color-Bold-Black { + color: var(--ansi-black); +} + +.-Color-Faint { + opacity: 0.5; +} + +.-Color-Bold { + font-weight: bold; +} + +.-Color-Black-BGBlack, +.-Color-BGBlack, +.-Color-Red-BGBlack, +.-Color-Green-BGBlack, +.-Color-Yellow-BGBlack, +.-Color-Blue-BGBlack, +.-Color-Magenta-BGBlack, +.-Color-Cyan-BGBlack, +.-Color-White-BGBlack { + background-color: var(--ansi-black); +} + +.-Color-Black-BGRed, +.-Color-BGRed, +.-Color-Red-BGRed, +.-Color-Green-BGRed, +.-Color-Yellow-BGRed, +.-Color-Blue-BGRed, +.-Color-Magenta-BGRed, +.-Color-Cyan-BGRed, +.-Color-White-BGRed { + background-color: var(--ansi-red); +} + +.-Color-Black-BGGreen, +.-Color-BGGreen, +.-Color-Red-BGGreen, +.-Color-Green-BGGreen, +.-Color-Yellow-BGGreen, +.-Color-Blue-BGGreen, +.-Color-Magenta-BGGreen, +.-Color-Cyan-BGGreen, +.-Color-White-BGGreen { + background-color: var(--ansi-green); +} + +.-Color-Black-BGYellow, +.-Color-BGYellow, +.-Color-Red-BGYellow, +.-Color-Green-BGYellow, +.-Color-Yellow-BGYellow, +.-Color-Blue-BGYellow, +.-Color-Magenta-BGYellow, +.-Color-Cyan-BGYellow, +.-Color-White-BGYellow { + background-color: var(--ansi-yellow); +} + +.-Color-Black-BGBlue, +.-Color-BGBlue, +.-Color-Red-BGBlue, +.-Color-Green-BGBlue, +.-Color-Yellow-BGBlue, +.-Color-Blue-BGBlue, +.-Color-Magenta-BGBlue, +.-Color-Cyan-BGBlue, +.-Color-White-BGBlue { + background-color: var(--ansi-blue); +} + +.-Color-Black-BGMagenta, +.-Color-BGMagenta, +.-Color-Red-BGMagenta, +.-Color-Green-BGMagenta, +.-Color-Yellow-BGMagenta, +.-Color-Blue-BGMagenta, +.-Color-Magenta-BGMagenta, +.-Color-Cyan-BGMagenta, +.-Color-White-BGMagenta { + background-color: var(--ansi-magenta); +} + +.-Color-Black-BGCyan, +.-Color-BGCyan, +.-Color-Red-BGCyan, +.-Color-Green-BGCyan, +.-Color-Yellow-BGCyan, +.-Color-Blue-BGCyan, +.-Color-Magenta-BGCyan, +.-Color-Cyan-BGCyan, +.-Color-White-BGCyan { + background-color: var(--ansi-cyan); +} + +.-Color-Black-BGWhite, +.-Color-BGWhite, +.-Color-Red-BGWhite, +.-Color-Green-BGWhite, +.-Color-Yellow-BGWhite, +.-Color-Blue-BGWhite, +.-Color-Magenta-BGWhite, +.-Color-Cyan-BGWhite, +.-Color-White-BGWhite { + background-color: var(--ansi-white); +} + +.-Color-Black-BGBlack, +.-Color-Red-BGRed, +.-Color-Blue-BGBlue { + text-shadow: 0 0 1px var(--ansi-white); +} + +.-Color-Green-BGGreen, +.-Color-Yellow-BGYellow, +.-Color-Cyan-BGCyan, +.-Color-White-BGWhite, +.-Color-Magenta-BGMagenta, +.-Color-Cyan-BGGreen, +.-Color-Green-BGCyan { + text-shadow: 0 0 1px var(--ansi-black); +} diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..dbe115d --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,334 @@ +# Using + +## Using commands + +After you install Ansible-lint, run `ansible-lint --help` to display available +commands and their options. + +```console exec="1" source="console" +$ ansible-lint --help +``` + +### Command output + +Ansible-lint prints output on both `stdout` and `stderr`. + +- `stdout` displays rule violations. +- `stderr` displays logging and free-form messages like statistics. + +Most `ansible-lint` examples use pep8 as the output format (`-p`) which is +machine parseable. + +Ansible-lint also print errors using their [annotation] format when it detects +the `GITHUB_ACTIONS=true` and `GITHUB_WORKFLOW=...` variables. + +[annotation]: + https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message + +## Caching + +For optimal performance, Ansible-lint creates caches with installed or mocked +roles, collections, and modules in the `{project_dir}/.cache` folder. The +location of `{project_dir}` is passed with a command line argument, determined +by the location of the configuration file, git project top-level directory, or +user home directory. + +To perform faster re-runs, Ansible-lint does not automatically clean the cache. +If required you can do this manually by simply deleting the `.cache` folder. +Ansible-lint creates a new cache on the next invocation. + +You should add the `.cache` folder to the `.gitignore` file in your git +repositories. + +## Gradual adoption + +For an easier gradual adoption, adopters should consider [ignore +file][configuring.md#ignoring-rules-for-entire-files] feature. This allows the +quick introduction of a linter pipeline for preventing addition of new +violations, while known violations are ignored. Some people can work on +addressing these historical violations while others may continue to work on +other maintenance tasks. + +The deprecated `--progressive` mode was removed in v6.16.0 as it added code +complexity and performance overhead. It also presented several corner cases +where it failed to work as expected and caused false negatives. + +## Linting playbooks and roles + +Ansible-lint recommends following the [collection structure layout] whether you +plan to build a collection or not. + +Following that layout assures the best integration with all ecosystem tools +because it helps those tools better distinguish between random YAML files and +files managed by Ansible. When you call `ansible-lint` without arguments, it +uses internal heuristics to determine file types. + +You can specify the list of **roles** or **playbooks** that you want to lint +with the `-p` argument. For example, to lint `examples/playbooks/play.yml` and +`examples/roles/bobbins`, use the following command: + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -p examples/playbooks/play.yml examples/roles/bobbins +``` + +[collection structure layout]: + https://docs.ansible.com/ansible-core/devel/dev_guide/developing_collections_structure.html#collection-structure + +## Running example playbooks + +Ansible-lint includes an `ansible-lint/examples` folder that contains example +playbooks with different rule violations and undesirable characteristics. You +can run `ansible-lint` on the example playbooks to observe Ansible-lint in +action, as follows: + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -p examples/playbooks/example.yml +``` + +Ansible-lint also handles playbooks that include other playbooks, tasks, +handlers, or roles, as the `examples/playbooks/include.yml` example +demonstrates. + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -q -p examples/playbooks/include.yml +``` + +## Output formats + +### pep8 + +```console exec="1" source="console" returncode="2" +$ ansible-lint --offline -q -f pep8 examples/playbooks/norole.yml +``` + +### SARIF JSON + +Using `--format sarif` or `--format json` the linter will output on stdout a +report in [SARIF] + +We also have an option `--sarif-file FILE` option that can make the linter dump +the output to a file while not altering its normal stdout output. This can be +used in CI/CD pipelines. + +```bash exec="1" source="tabbed-left" result="json" returncode="2" +ansible-lint --offline -q -f sarif examples/playbooks/norole.yml +``` + +### Code Climate JSON + +You can generate `JSON` reports based on the [Code Climate] specification as the +`examples/playbooks/norole.yml` example demonstrates. + +```bash exec="1" source="tabbed-left" result="json" returncode="2" +ansible-lint --offline -q -f codeclimate examples/playbooks/norole.yml +``` + +Historically `-f json` was used to generate Code Climate JSON reports but in +never versions we switched its meaning point SARIF JSON format instead. + +!!! warning + + When possible we recommend using the [SARIF](#sarif-json) format instead of the Code Climate + as that one is more complete and has a full specification and also a JSON + validation schema. Code Climate format does not expose our severity + levels because we use that field to map warnings + as `minor` and errors as `major` issues. + +## Specifying rules at runtime + +By default, `ansible-lint` applies rules found in +`ansible-lint/src/ansiblelint/rules`. Use the `-r /path/to/custom-rules` option +to specify the directory path to a set of custom rules. For multiple custom rule +sets, pass each set with a separate `-r` option. + +You can also combine the default rules with custom rules with the `-R` option +along with one or more `-r` options. + +### Including rules with tags + +Each rule has an associated set of one or more tags. Use the `-T` option to view +the list of tags for each available rule. + +You can then use the `-t` option to specify a tag and include the associated +rules in the lint run. For example, the following `ansible-lint` command applies +only the rules associated with the _idempotency_ tag: + +```console exec="1" source="console" returncode="0" +$ ansible-lint -t idempotency playbook.yml +``` + +The following shows the available tags in an example set of rules and the rules +associated with each tag: + +```bash exec="1" source="console" +ansible-lint -T 2>/dev/null +``` + +### Excluding rules with tags + +To exclude rules by identifiers or tags, use the `-x SKIP_LIST` option. For +example, the following command applies all rules except those with the +_formatting_ and _metadata_ tags: + +```bash +$ ansible-lint -x formatting,metadata playbook.yml +``` + +### Ignoring rules + +To only warn about rules, use the `-w WARN_LIST` option. For example, the +following command displays only warns about violations with rules associated +with the `experimental` tag: + +```console +$ ansible-lint -w experimental playbook.yml +``` + +By default, the `WARN_LIST` includes the `['experimental']` tag. If you define a +custom `WARN_LIST` you must add `'experimental'` so that Ansible-lint does not +fail against experimental rules. + +## Muting warnings to avoid false positives + +Not all linting rules are precise, some are general rules of thumb. Advanced +_git_, _yum_ or _apt_ usage, for example, can be difficult to achieve in a +playbook. In cases like this, Ansible-lint can incorrectly trigger rule +violations. + +To disable rule violations for specific tasks, and mute false positives, add +`# noqa: [rule_id]` to the end of the line. It is best practice to add a comment +that explains why rules are disabled. + +You can add the `# noqa: [rule_id]` comment to the end of any line in a task. +You can also skip multiple rules with a space-separated list. + +```yaml +- name: This task would typically fire git-latest and partial-become rules + become_user: alice # noqa: git-latest partial-become + ansible.builtin.git: src=/path/to/git/repo dest=checkout +``` + +If the rule is line-based, `# noqa: [rule_id]` must be at the end of the line. + +```yaml +- name: This would typically fire jinja[spacing] + get_url: + url: http://example.com/file.conf + dest: "{{dest_proj_path}}/foo.conf" # noqa: jinja[spacing] +``` + +If you want Ansible-lint to skip a rule entirely, use the `-x` command line +argument or add it to `skip_list` in your configuration. + +The least preferred method of skipping rules is to skip all task-based rules for +a task, which does not skip line-based rules. You can use the +`skip_ansible_lint` tag with all tasks or the `warn` parameter with the +_command_ or _shell_ modules, for example: + +```yaml +- name: This would typically fire no-free-form + command: warn=no chmod 644 X + +- name: This would typically fire command-instead-of-module + command: git pull --rebase + args: + warn: false + +- name: This would typically fire git-latest + git: src=/path/to/git/repo dest=checkout + tags: + - skip_ansible_lint +``` + +## Applying profiles + +Ansible-lint profiles allow content creators to progressively improve the +quality of Ansible playbooks, roles, and collections. + +During early development cycles, you need Ansible-lint rules to be less strict. +Starting with the minimal profile ensures that Ansible can load your content. As +you move to the next stage of developing content, you can gradually apply +profiles to avoid common pitfalls and brittle complexity. Then, when you are +ready to publish or share your content, you can use the `shared` and +`production` profiles with much stricter rules. These profiles harden security, +guarantee reliability, and ensure your Ansible content is easy for others to +contribute to and use. + +!!! note + + Tags such as `opt-in` and `experimental` do not take effect for rules that are included in profiles, directly or indirectly. + If a rule is in a profile, Ansible-lint applies that rule to the content. + +After you install and configure `ansible-lint`, you can apply profiles as +follows: + +1. View available profiles with the `--list-profiles` flag. + + ```bash + ansible-lint --list-profiles + ``` + +2. Specify a profile with the `--profile` parameter to lint your content with + those rules, for example: + +- Enforce standard styles and formatting with the `basic` profile. + + ```bash + ansible-lint --profile=basic + ``` + +- Ensure automation consistency, reliability, and security with the `safety` + profile. + + ```bash + ansible-lint --profile=safety + ``` + +## Vaults + +As ansible-lint executes ansible, it also needs access to encrypted secrets. If +you do not give access to them or you are concerned about security implications, +you should consider refactoring your code to allow it to be linted without +access to real secrets: + +- Configure dummy fallback values that are used during linting, so Ansible will + not complain about undefined variables. +- Exclude the problematic files from the linting process. + +```yaml +--- +# Example of avoiding undefined variable error +foo: "{{ undefined_variable_name | default('dummy') }}" +``` + +Keep in mind that a well-written playbook or role should allow Ansible's syntax +check from passing on it, even if you do not have access to the vault. + +Internally ansible-lint runs `ansible-playbook --syntax-check` on each playbook +and also on roles. As ansible-code does not support running syntax-check +directly on roles, the linter will create temporary playbooks that only include +each role from your project. You will need to change the code of the role in a +way that it does not produce syntax errors when called without any variables or +arguments. This usually involves making use of `defaults/` but be sure that you +fully understand [variable precedence]. + +[code climate]: + https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types +[sarif]: + https://docs.oasis-open.org/sarif/sarif/v2.1.0/csprd01/sarif-v2.1.0-csprd01.html +[variable precedence]: + https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#understanding-variable-precedence + +## Dependencies and requirements + +Ansible-lint will recognize `requirements.yml` files used for runtime and +testing purposes and install them automatically. Valid locations for these files +are: + +- [`requirements.yml`](https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#installing-roles-and-collections-from-the-same-requirements-yml-file) +- `roles/requirements.yml` +- `collections/requirements.yml` +- `tests/requirements.yml` +- `tests/integration/requirements.yml` +- `tests/unit/requirements.yml` +- [`galaxy.yml`](https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html) -- cgit v1.2.3