ansible-lint: Usage, Options & Common CI Errors

Catch playbook and role problems before they ever reach a host.

ansible-lint checks playbooks, roles, and collections against best-practice rules. As a fast CI gate it flags deprecated syntax, risky patterns, and style issues before any real run.

What it does

ansible-lint statically analyzes Ansible content and reports rule violations with severity. Profiles (min, basic, moderate, safety, shared, production) let you ratchet strictness over time, and it can emit SARIF for code-scanning dashboards. It exits nonzero when violations at or above the configured level are found.

Common usage

# Lint everything ansible-lint can autodetect
ansible-lint

# Lint a specific playbook at a chosen strictness
ansible-lint site.yml --profile production

# CI: machine-readable output + non-zero on findings
ansible-lint -f sarif > ansible-lint.sarif

Common error in CI: rule violations fail the build

The gate fails with lines like "yaml[line-length] Line too long" or "risky-file-permissions File permissions unset or incorrect" and a nonzero exit, but nothing is fixed. Fix: run ansible-lint --fix locally to auto-correct what it can, commit, and address the rest; pin a profile (e.g. --profile basic) so a new ansible-lint release does not suddenly fail on stricter rules. Use a .ansible-lint config with skip_list/warn_list to triage rules deliberately rather than disabling the gate.

Key options

Related guides