Ansible-lint — Best Practices Checker for Ansible Playbooks

Introduction

Ansible-lint is a command-line tool that checks Ansible playbooks, roles, and collections for practices that could lead to bugs, security issues, or hard-to-maintain code. It enforces a curated set of rules inspired by Ansible community best practices.

What Ansible-lint Does

• Scans playbooks, roles, tasks, handlers, and vars files for rule violations
• Detects deprecated modules, incorrect FQCN usage, and risky shell commands
• Flags formatting issues like incorrect indentation and naming conventions
• Supports custom rules written in Python for organization-specific standards
• Integrates with CI pipelines to gate merges on lint compliance

Architecture Overview

Ansible-lint parses YAML playbook files using the Ansible parsing engine to build an internal task tree. It walks each task, play, and role against a rule registry, evaluating conditions defined in Python rule classes. Results are collected with severity levels (error, warning) and output in plain text, JSON, or SARIF for code scanning integrations.

Self-Hosting & Configuration

• Install via pip or pipx alongside your Ansible installation
• Place a .ansible-lint config file in your project root to customize rules
• Use skip_list to disable specific rules that conflict with your conventions
• Set warn_list to downgrade certain rules from errors to warnings
• Run in CI with --format json or --format sarif for GitHub Code Scanning

Key Features

• Extensive built-in rule set covering naming, deprecation, idempotency, and security
• Auto-fix capability for select rules (e.g., FQCN conversion)
• SARIF output for native integration with GitHub Advanced Security
• Custom rule support via Python classes for project-specific standards
• Profiles (min, basic, moderate, safety, shared, production) for progressive adoption

Comparison with Similar Tools

• yamllint — generic YAML linter; Ansible-lint understands Ansible semantics like tasks and roles
• ansible-review — older Ansible review tool; Ansible-lint is actively maintained and feature-rich
• Molecule — tests Ansible roles in containers; Ansible-lint performs static analysis without provisioning
• Checkov — IaC security scanner; Ansible-lint covers style and best practices beyond just security
• pre-commit hooks — Ansible-lint integrates as a pre-commit hook alongside other linters

FAQ

Q: Can I use it with Ansible collections? A: Yes. Ansible-lint supports linting collections, including meta files and plugin structure validation.

Q: How do I ignore a specific rule for one task? A: Add a noqa comment: # noqa: rule-id on the task line or use the skip_list in configuration.

Q: Does it support auto-fixing? A: Some rules support --fix mode, such as converting short module names to fully qualified collection names.

Q: What are profiles? A: Profiles group rules by strictness (min, basic, moderate, safety, shared, production), letting teams adopt linting progressively.

Sources

• https://github.com/ansible/ansible-lint
• https://ansible.readthedocs.io/projects/lint/