# Ansible-lint — Best Practices Checker for Ansible Playbooks

> A linting tool that checks Ansible playbooks, roles, and collections for style violations, anti-patterns, and potential bugs before they reach production.

## Install

Save in your project root:

# Ansible-lint — Best Practices Checker for Ansible Playbooks

## Quick Use
```bash
pip install ansible-lint
# Lint a playbook
ansible-lint site.yml
# Lint an entire roles directory
ansible-lint roles/
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-1da6cf2b
Author: AI Open Source