Ansible Lint (foundata extension)

Additional rules and conservative autofixes for foundata's Ansible playbook guidelines. This optional extension uses the stock Ansible Lint command.

Table of contents

• Installation
• Configuration
• Running checks
• Formatting and safety
• Continuous integration
• Troubleshooting
• Development
• Licensing, copyright
  • Trademarks
• Author information

Installation

Requires Python 3.12 or later and Ansible Lint 26.9.0 or later. Install the extension into the same environment as ansible-lint.

From your Ansible project, create a lint environment and install the extension from PyPI:

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python ansible-lint-foundata
. .venv/bin/activate

If you already have a lint environment, use its Python path in the install command and activate that environment instead. To install from source or test a release artifact, replace the package name with a checkout or wheel path. Runtime dependencies, including Ansible Lint, are installed with the extension.

Use a regular, non-editable installation. Ansible Lint discovers the installed rules automatically; you do not need a local rule directory or sys.path changes. For work on the extension itself, use the development setup.

Configuration

All foundata rules are opt-in, including under stock profiles. Add their IDs to enable_list in your Ansible project's .ansible-lint. This example enables the condition-list rule alongside the stock production profile:

---
profile: "production"
strict: true
enable_list:
  - "foundata-condition-list"

For the broader guideline baseline, adapt both tested consumer files:

• .ansible-lint enables the adopted foundata rules and stock jinja-template-extension and loop-var-prefix checks.
• .yamllint accepts formatter output, requires document starts and lowercase booleans, and prefers double quotes without forcing them on local identifiers or implicit expressions.

The loop-variable pattern requires a private role prefix and purpose suffix. If the role's public prefix includes its collection, add that component to loop_var_prefix; the baseline cannot infer it.

Review the rule contract before adopting the baseline. It enforces its SHOULD-level checks as errors; document that choice in your project. foundata-string-quotes and foundata-parameter-order require separate adoption and are not enabled in the consumer example.

Running checks

Run the installed command from your Ansible project:

ansible-lint --list-rules --format brief
ansible-lint

The listing confirms discovery, not whether a rule is enabled. The lint run uses your configuration and reports findings with links to the relevant guideline sections.

Generated changelogs/changelog.yaml should be excluded from Ansible Lint and validated separately with antsibull-changelog lint-changelog-yaml; validate fragments with antsibull-changelog lint.

Formatting and safety

To apply available fixes, run:

ansible-lint --fix
git diff
ansible-lint

Ansible Lint owns YAML formatting. This package does not restore blank lines removed by --fix, require a blank line at EOF, or replace its serializer. Fixes wrap scalar conditions and handler topics in lists. Extended task ordering is diagnostic-only; stock key-order owns its autofix. The extension does not rename handler topics, change permissions, reinterpret process exit codes, or change play termination behavior. Review every fix.

Ansible Lint 26.9.0 returns exit code 8 when all reported violations were fixed. Run the final check even after that exit code; it should return zero once no violations remain.

See the rule contract for exact coverage, allowed exceptions, and remaining review requirements.

Continuous integration

CI that requires these checks must install the extension and verify both discovery and execution:

1. Run ansible-lint --list-rules --format brief in the lint environment using the project's configuration. Fail if any enabled custom rule ID is absent.
2. Run known-invalid fixtures to verify that every adopted rule reports its expected violation. Listing bypasses profile filtering and does not prove execution.
3. Lint the project with the same configuration and environment.

Without this package, the tested Ansible Lint version continues to run stock checks even if custom IDs remain in enable_list. That fallback is for optional local use. Do not pass missing custom IDs explicitly to --fix=....

Troubleshooting

• If no foundata-* rules appear in the listing, check that the extension and the command are installed in the same environment. Reinstall the extension without editable mode.
• If a listed rule does not report an expected violation, check enable_list, skip_list, local noqa comments, and the rule's analysis boundaries. Runtime values and unresolved references may be outside its scope.
• If a finding remains after --fix, check the rule's autofix support. Most rules require a reviewed manual change; extended task ordering is one example.

Development

See DEVELOPMENT.md for the contributor environment, test suite, package layout, and release procedure.

Licensing, copyright

Copyright (c) 2026, foundata GmbH (https://foundata.com)

This project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: GPL-3.0-or-later), see LICENSES/GPL-3.0-or-later.txt for the full text.

REUSE.toml records licensing and copyright information in a human- and machine-readable format, including any different terms for third-party components. The repository follows the REUSE specification. Use reuse spdx to create an SPDX software bill of materials (SBOM).

Trademarks

Third-party trademarks used in this repository:

• Ansible® and Red Hat® are trademarks of Red Hat, LLC, registered in the United States and other countries.

Their use here is purely descriptive and does not imply any affiliation with or endorsement by the trademark holders.

Own and licensed trademarks used in this repository:

• foundata® is a trademark of IPAM GmbH, registered in Germany and the European Union, licensed to foundata GmbH.

Author information

This project was created and is maintained by foundata.