ansible-lint

Lint a specific playbook and a role directory

$ ansible-lint [path/to/playbook_file] [path/to/role_directory]

$ ansible-lint [[-x|--exclude-rules]] [rule1,rule2,...] [path/to/playbook_file]

$ ansible-lint [[-o|--offline]] [[-p|--parseable]] [path/to/playbook_file]

$ ansible-lint [[-r|--rules]] [path/to/custom_rules_directory] [path/to/playbook_file]

$ ansible-lint [path/to/project_directory]

ansible-lint [OPTIONS] [PATH...]

PATH...
    One or more paths to Ansible files (e.g., playbooks, roles, or directories) to lint. If no path is provided, it typically lints the current working directory.

-c CONFIG_FILE, --config-file CONFIG_FILE
    Specify a YAML configuration file to override default settings and rule configurations. Common locations include .ansible-lint in the project root.

--fix
    Attempt to automatically fix detected issues. Not all issues can be fixed automatically, and manual review of changes is recommended.

-f FORMAT, --format FORMAT
    Choose the output format for violations. Common options include plain (default), json, and sarif for integration with other tools.

--parseable
    Output violations in a machine-readable, parseable format, typically without additional decorative elements.

-q, --quiet
    Suppress all output except for violations. Useful in CI/CD environments where only errors need to be reported.

-v, --verbose
    Increase verbosity of output. Use multiple -v for more detailed debugging information (e.g., -vvv).

--strict
    Return an exit code of 1 even if only warnings are found. By default, only errors cause a non-zero exit code.

--skip-list RULE_ID_LIST
    A comma-separated list of rule IDs to skip during the linting process. E.g., --skip-list 201,305.

--enable-list RULE_ID_LIST
    A comma-separated list of rule IDs to enable, even if they are generally disabled by default or via configuration.

--disable-list RULE_ID_LIST
    A comma-separated list of rule IDs to disable, overriding any configuration that might enable them.

--warn-list RULE_ID_LIST
    A comma-separated list of rule IDs that should be downgraded from errors to warnings.

-p PROJECT_DIR, --project-dir PROJECT_DIR
    Path to the project directory. This helps ansible-lint locate related files, roles, and collections.

--rules-dir DIR
    Specify one or more directories containing custom linting rules. Can be specified multiple times.

--exclude EXCLUDE_PATH
    Exclude specific paths or files from being linted. Can be specified multiple times.

--offline
    Do not attempt to download collection schemas from the internet. Useful for environments with restricted network access.

--nocolor
    Disable colored output. Useful when output is redirected to a file or in terminals that don't support color.

--version
    Show the program's version number and exit.

ansible-lint is a command-line utility designed to help maintain and improve the quality of Ansible content, including playbooks, roles, and collections. It analyzes Ansible YAML files against a set of predefined rules and best practices, identifying potential errors, deprecated features, style inconsistencies, and security issues.

By enforcing coding standards, ansible-lint assists developers in writing more reliable, readable, and maintainable Ansible code. It provides actionable feedback, often with suggestions for remediation, and can even automatically fix some common issues using its --fix option. It's an invaluable tool for individual developers and highly beneficial when integrated into Continuous Integration/Continuous Delivery (CI/CD) pipelines to ensure code quality before deployment.

ansible-lint requires Python 3.8+ and needs to be installed via pip. While it is highly effective, it may sometimes produce false positives, or certain rules might not align with specific project conventions. In such cases, fine-tuning rule configurations, using skip lists, or developing custom rules is necessary. The --fix option should always be used with caution and its changes reviewed, as automatic fixes might not always align perfectly with desired code style or logic.

ansible-lint can be configured using a YAML file, typically named .ansible-lint, located in the root of your Ansible project. This file allows you to define default rule lists (enable/disable/warn), specify custom rules directories, set verbosity, exclude paths, and more. This centralizes linting settings, making them consistent across a team or CI/CD pipelines. Alternatively, configuration can be specified in pyproject.toml under the [tool.ansible-lint] section.

Users can extend ansible-lint's capabilities by writing custom rules in Python. These rules allow organizations to enforce internal best practices or validate highly specific architectural patterns not covered by the default rule set. Custom rules are placed in a directory specified in the configuration file or via the --rules-dir option.

Due to its command-line interface and configurable exit codes, ansible-lint is perfectly suited for integration into CI/CD pipelines. It can be run as a pre-commit hook or as part of a build step to automatically check Ansible content for quality and compliance before merging code or deploying changes, ensuring a higher standard of code quality and reducing post-deployment issues.

Initially developed as a community-driven project, ansible-lint has grown to become an essential part of the Ansible ecosystem, officially supported by Ansible project maintainers. Its evolution reflects the increasing demand for code quality, maintainability, and automated testing within the Ansible community. Over time, it has expanded its rule set, improved performance, and integrated more deeply with Ansible's internal structures, including support for Ansible collections and robust configuration options.

ansible(1), yamllint(1)