Ansible Lint: Complete Guide to Linting and Best Practices for Playbooks
By Luca Berton · Published 2024-01-01 · Category: installation
Master ansible-lint to enforce best practices in your playbooks. Install, configure, fix common warnings, create custom rules, integrate with CI/CD, and automate code quality for Ansible automation.
What Is ansible-lint?
ansible-lint is the official linting tool for Ansible content. It checks playbooks, roles, and collections against a set of rules that enforce best practices, catch common mistakes, and improve code quality.
Think of it as ESLint for Ansible — it won't run your playbooks, but it will tell you what's wrong before you do.
Install
Basic Usage
Understanding Rules
Rule Categories
| Tag | Description | Example | |-----|-------------|---------| | command-instead-of-module | Use modules instead of shell/command | Use ansible.builtin.apt not apt-get install | | deprecated | Deprecated syntax or features | with_items → loop | | experimental | New rules being tested | Various | | formatting | YAML formatting issues | Indentation, trailing spaces | | idempotency | Non-idempotent tasks | Missing creates/removes on command | | metadata | Role/collection metadata issues | Missing meta/main.yml | | name | Task naming conventions | Missing or badly formatted names | | no-changed-when | Missing changed_when | Shell/command without change detection | | partial-become | Inconsistent privilege escalation | become on some tasks but not play | | risky | Potentially dangerous operations | ignore_errors: true | | schema | Schema validation failures | Invalid playbook structure | | syntax | YAML/Ansible syntax errors | Bad indentation, invalid keywords | | unpredictability | Non-deterministic behavior | git without version | | yaml | YAML best practices | Truthy values, line length |
Most Common Warnings and Fixes
name[missing] — Tasks should be named
fqcn[action-core] — Use FQCN for modules
no-changed-when — Commands need change detection
command-instead-of-module — Use modules
yaml[truthy] — Avoid truthy values
risky-file-permissions — Set explicit permissions
no-free-form — Avoid free-form syntax
jinja[spacing] — Consistent Jinja2 spacing
Configuration
.ansible-lint Configuration File
Profiles
Profiles are preset rule bundles, from permissive to strict:
| Profile | Rules | Best For | |---------|-------|----------| | min | Syntax only | Legacy codebases | | basic | min + essential rules | Getting started | | moderate | basic + style rules | Most teams | | safety | moderate + security rules | Security-conscious teams | | shared | safety + collaboration rules | Open source / shared content | | production | All rules | Enterprise / certified content |
Auto-Fix
ansible-lint can automatically fix many issues:
Auto-fixable rules include: • yaml[truthy] — yes/no → true/false • yaml[octal-values] — Octal file modes • fqcn[action-core] — Short module names → FQCNs • name[casing] — Task name capitalization • jinja[spacing] — Jinja2 template spacing • no-free-form — Free-form to structured arguments
CI/CD Integration
GitHub Actions
GitLab CI
Pre-commit Hook
Custom Rules
Create custom rules for your organization's standards:
ansible-lint with VS Code
Install the Ansible extension for VS Code:
This gives you real-time linting feedback as you write playbooks — red squiggles under issues, hover for explanations, quick-fix suggestions.
Integrating with Molecule
Or in newer Molecule versions, add to your CI pipeline to run lint before converge.
Common Workflow
FAQ
What's the difference between ansible-lint and yamllint?
yamllint checks generic YAML syntax and formatting. ansible-lint checks Ansible-specific best practices — module usage, task naming, idempotency, deprecations, and security. ansible-lint includes yamllint rules via the yaml[] rule set, so you typically only need ansible-lint.
Should I use --fix in CI/CD?
No. Use --fix locally during development. In CI/CD, run ansible-lint without --fix — it should only report errors, not modify code. If it finds issues, the PR fails and the developer fixes them locally.
How do I ignore a specific rule for one task?
Add a # noqa comment:
Or for all rules on a task: # noqa: all
Which profile should my team use?
Start with basic or moderate. Move to safety or production as your codebase matures. Avoid starting with production on a legacy codebase — you'll get hundreds of warnings and developers will just skip it.
Does ansible-lint slow down CI pipelines?
No. ansible-lint is fast — it typically completes in seconds even for large codebases. It only parses YAML files, it doesn't execute anything.
Conclusion
ansible-lint is essential for maintaining quality Ansible automation. Start with a moderate profile, integrate into your CI/CD pipeline and pre-commit hooks, use --fix for auto-fixable issues, and gradually increase strictness as your codebase improves. The key rules to enforce from day one: FQCN module names, task names, changed_when on commands, explicit file permissions, and true/false instead of yes/no.
Related Articles • Ansible Documentation Complete Guide • Ansible Collection Role Testing with Molecule • Ansible CI/CD Pipeline Integration • Ansible Best Practices: ignore_errors • Install Ansible Complete Guide • Install ansible-lint on macOS • Ansible-Lint Rule Analysis and Best Practices • Exploring Ansible-Lint Profiles
Category: installation