Skip to content

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:

$ git clone --recursive git@github.com:your-name/ansible-lint
$ cd ansible-lint
$ # Recommended: Initialize and activate a Python virtual environment
$ pip install --upgrade pip
$ pip install -e '.[test]'       # Install testing dependencies
$ tox run -e lint,pkg,docs,py  # Ensure subset of tox tests work in clean checkout
$ git checkout -b your-branch-name
# DO SOME CODING HERE
$ tox run -e lint,pkg,docs,py  # Ensure subset of tox tests work with your changes
$ 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.

Talk to us

Connect with the Ansible community!

Join the Ansible forum to ask questions, get help, and interact with the community.

  • Get Help: get help or help others. Please add appropriate tags if you start new discussions, for example use the ansible-lint or devtools tags.
  • Social Spaces: meet and interact with fellow enthusiasts.
  • News & Announcements: track project-wide announcements including social events.

To get release announcements and important changes from the community, see the Bullhorn newsletter.

For a live chat experience join the #devtools:ansible.com Matrix room.

You can find more information in the Ansible communication guide.

Possible security bugs should be reported via email to security@ansible.com.

Code of Conduct

As with all Ansible projects, we have a Code of Conduct.

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.

uv pip tree --package ansible-lint --show-version-specifiers --strict
Using Python 3.14.6 environment at: .tox/docs
ansible-lint v26.6.1.dev5
├── ansible-compat v26.6.0 [required: >=26.3.0]
│   ├── ansible-core v2.21.1 [required: >=2.16]
│   │   ├── cryptography v49.0.0 [required: *]
│   │   │   └── cffi v2.0.0 [required: >=2.0.0]
│   │   │       └── pycparser v3.0 [required: *]
│   │   ├── jinja2 v3.1.6 [required: >=3.1.0]
│   │   │   └── markupsafe v3.0.3 [required: >=2.0]
│   │   ├── packaging v26.2 [required: *]
│   │   ├── pyyaml v6.0.3 [required: >=5.1]
│   │   └── resolvelib v1.2.1 [required: >=0.8.0, <2.0.0]
│   ├── jsonschema v4.26.0 [required: >=4.6.0]
│   │   ├── attrs v26.1.0 [required: >=22.2.0]
│   │   ├── jsonschema-specifications v2025.9.1 [required: >=2023.3.6]
│   │   │   └── referencing v0.37.0 [required: >=0.31.0]
│   │   │       ├── attrs v26.1.0 [required: >=22.2.0]
│   │   │       └── rpds-py v2026.6.3 [required: >=0.7.0]
│   │   ├── referencing v0.37.0 [required: >=0.28.4] (*)
│   │   └── rpds-py v2026.6.3 [required: >=0.25.0]
│   ├── packaging v26.2 [required: >=22.0]
│   ├── pyyaml v6.0.3 [required: >=6.0.1]
│   └── subprocess-tee v0.4.2 [required: >=0.4.1]
├── ansible-core v2.21.1 [required: >=2.16.14] (*)
├── black v26.5.1 [required: >=24.3.0]
│   ├── click v8.4.2 [required: >=8.0.0]
│   ├── mypy-extensions v1.1.0 [required: >=0.4.3]
│   ├── packaging v26.2 [required: >=22.0]
│   ├── pathspec v1.1.1 [required: >=1.0.0]
│   ├── platformdirs v4.10.0 [required: >=2]
│   └── pytokens v0.4.1 [required: ~=0.4.0]
├── cffi v2.0.0 [required: >=1.15.1] (*)
├── cryptography v49.0.0 [required: >=37] (*)
├── distro v1.9.0 [required: >=1.9.0]
├── filelock v3.29.5 [required: >=3.8.2]
├── jsonschema v4.26.0 [required: >=4.10.0] (*)
├── packaging v26.2 [required: >=22.0]
├── pathspec v1.1.1 [required: >=1.0.3, <1.2.0]
├── pyyaml v6.0.3 [required: >=6.0.1]
├── referencing v0.37.0 [required: >=0.36.2] (*)
├── ruamel-yaml v0.19.1 [required: >=0.18.11]
├── subprocess-tee v0.4.2 [required: >=0.4.1]
├── wcmatch v10.2.1 [required: >=8.5.0]
│   └── bracex v3.0 [required: >=3.0]
└── yamllint v1.38.0 [required: >=1.38.0]
    ├── pathspec v1.1.1 [required: >=1.0.0]
    └── pyyaml v6.0.3 [required: *]
(*) Package tree already displayed

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 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: tox -e py -- -k NewRule
  • Run tox in order to run all ansible-lint tests. Adding a new rule can break some other tests. Update them if needed.
  • Run ansible-lint -L and check that the rule description renders correctly.
  • Build the docs using tox -e docs and check that the new rule is displayed correctly in them.

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, and let us know how we can improve our documentation.