diff options
Diffstat (limited to 'docs')
73 files changed, 1387 insertions, 0 deletions
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 --- /dev/null +++ b/docs/.nojekyll 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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg width="100%" height="100%" viewBox="0 0 16 16" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;"> + <path d="M6,2L6,2.984L5.911,2.984C5.711,2.984 5.524,3.024 5.348,3.105C5.175,3.183 5.022,3.289 4.891,3.424C4.764,3.555 4.661,3.71 4.582,3.892C4.508,4.072 4.471,4.26 4.471,4.459C4.471,4.687 4.475,4.913 4.483,5.137C4.491,5.361 4.491,5.583 4.483,5.802C4.479,6.02 4.461,6.233 4.428,6.443C4.395,6.652 4.339,6.853 4.26,7.045C4.181,7.238 4.073,7.423 3.936,7.597C3.823,7.741 3.685,7.875 3.523,8C3.685,8.125 3.823,8.259 3.936,8.403C4.073,8.577 4.181,8.762 4.26,8.955C4.339,9.148 4.395,9.35 4.428,9.563C4.461,9.769 4.479,9.982 4.483,10.204C4.491,10.42 4.491,10.641 4.483,10.869C4.475,11.089 4.471,11.313 4.471,11.541C4.471,11.744 4.508,11.935 4.582,12.114C4.661,12.291 4.764,12.447 4.891,12.582C5.022,12.713 5.174,12.819 5.348,12.901C5.523,12.978 5.711,13.016 5.911,13.016L6,13.016L6,14L5.911,14C5.597,14 5.294,13.938 5.001,13.815C4.708,13.692 4.449,13.515 4.226,13.285C4.003,13.056 3.838,12.805 3.733,12.532L3.732,12.531C3.634,12.265 3.568,11.99 3.535,11.707L3.535,11.706C3.507,11.422 3.499,11.132 3.511,10.836C3.523,10.546 3.529,10.257 3.529,9.967C3.529,9.769 3.49,9.58 3.412,9.401L3.411,9.399C3.337,9.219 3.234,9.064 3.104,8.934L3.102,8.932C2.976,8.798 2.825,8.692 2.647,8.614L2.646,8.613C2.47,8.532 2.285,8.492 2.089,8.492L2,8.492L2,7.508L2.089,7.508C2.285,7.508 2.471,7.47 2.647,7.393C2.825,7.311 2.976,7.204 3.103,7.074C3.234,6.939 3.337,6.783 3.412,6.606L3.412,6.605C3.49,6.426 3.529,6.236 3.529,6.033C3.529,5.743 3.523,5.454 3.511,5.164C3.499,4.868 3.507,4.581 3.535,4.301L3.535,4.299C3.568,4.012 3.634,3.735 3.732,3.469L3.733,3.468C3.838,3.195 4.003,2.944 4.226,2.715C4.449,2.485 4.708,2.308 5.001,2.185C5.294,2.062 5.597,2 5.911,2L6,2ZM13.923,8.492L14,8.492L14,7.508L13.911,7.508C13.715,7.508 13.53,7.468 13.354,7.387L13.353,7.386C13.175,7.308 13.024,7.202 12.898,7.068L12.896,7.066C12.766,6.936 12.663,6.781 12.589,6.601L12.588,6.599C12.51,6.42 12.471,6.231 12.471,6.033C12.471,5.743 12.477,5.454 12.489,5.164C12.501,4.868 12.493,4.578 12.465,4.295L12.465,4.293C12.432,4.01 12.366,3.735 12.268,3.469L12.267,3.468C12.162,3.195 11.997,2.944 11.774,2.715C11.551,2.485 11.292,2.308 10.999,2.185C10.706,2.062 10.403,2 10.089,2L10,2L10,2.984L10.089,2.984C10.289,2.984 10.477,3.022 10.652,3.099C10.826,3.181 10.978,3.287 11.109,3.418C11.236,3.553 11.339,3.709 11.418,3.886C11.492,4.065 11.529,4.256 11.529,4.459C11.529,4.687 11.525,4.911 11.517,5.131C11.509,5.359 11.509,5.58 11.517,5.796C11.521,6.018 11.539,6.231 11.572,6.437C11.605,6.65 11.661,6.852 11.74,7.045C11.819,7.238 11.927,7.423 12.064,7.597C12.177,7.741 12.315,7.875 12.477,8C12.467,8.008 12.456,8.016 12.446,8.025C12.976,8.083 13.476,8.246 13.923,8.492Z" style="fill:rgb(128,128,128);"/> + <path d="M12,9C11.407,9 10.827,9.176 10.333,9.506C9.84,9.835 9.455,10.304 9.228,10.852C9.001,11.4 8.942,12.003 9.058,12.585C9.173,13.167 9.459,13.702 9.879,14.121C10.298,14.541 10.833,14.827 11.415,14.942C11.997,15.058 12.6,14.999 13.148,14.772C13.696,14.545 14.165,14.16 14.494,13.667C14.824,13.173 15,12.593 15,12C14.999,11.205 14.683,10.442 14.12,9.88C13.558,9.317 12.795,9.001 12,9Z" style="fill:rgb(128,128,128);fill-rule:nonzero;"/> +</svg> diff --git a/docs/_static/images/ansible-lint-512.png b/docs/_static/images/ansible-lint-512.png Binary files differnew file mode 100644 index 0000000..30ed574 --- /dev/null +++ b/docs/_static/images/ansible-lint-512.png diff --git a/docs/_static/images/favicon.ico b/docs/_static/images/favicon.ico Binary files differnew file mode 100644 index 0000000..23ad7da --- /dev/null +++ b/docs/_static/images/favicon.ico diff --git a/docs/_static/images/logo_invert.png b/docs/_static/images/logo_invert.png Binary files differnew file mode 100644 index 0000000..49e0897 --- /dev/null +++ b/docs/_static/images/logo_invert.png 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 <filename>` 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 +<mailto:security@ansible.com>. + +## 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.<your_custom_rules_subdir> + package_dir = + ansiblelint.rules.custom.<your_custom_rules_subdir> = <your_rules_source_code_subdir> + ``` + +3. Install the Python package into + `<ansible_lint_custom_rules_dir>/custom/<your_custom_rules_subdir>/`. 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 Binary files differnew file mode 100644 index 0000000..ea4ebc1 --- /dev/null +++ b/docs/images/favicon.ico diff --git a/docs/images/logo.png b/docs/images/logo.png Binary files differnew file mode 100644 index 0000000..f3626b0 --- /dev/null +++ b/docs/images/logo.png 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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg width="100%" height="100%" viewBox="0 0 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;"> + <g id="ansible-aap"> + <path d="M128,0C198.645,0 256,57.355 256,128C256,198.645 198.645,256 128,256C57.355,256 0,198.645 0,128C0,57.355 57.355,0 128,0ZM189.094,178.686L138.002,55.958C136.786,52.714 133.677,50.416 130.163,50.551C126.513,50.416 123.269,52.714 122.053,55.958L66.23,190.446L85.423,190.446L107.455,135.029L173.55,188.418C175.442,190.31 178.011,191.392 180.579,191.527C185.58,191.662 189.77,187.742 189.905,182.606L189.905,182.336C189.77,181.119 189.499,179.903 189.094,178.686ZM130.298,78.125L163.413,159.899L113.402,120.431L130.298,78.125Z" style="fill:white;"/> + </g> +</svg> 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 <will@thames.id.au> +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 @@ +<!--- +Do not manually edit, generated from generate_docs.py +--> + +# 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) |
