Skip to content

Configuration

Customize how Ansible-lint runs against automation content to suit your needs. You can ignore certain rules, enable opt-in rules, and control various other settings.

Ansible-lint loads configuration from a file in the current working directory or from a file that you specify in the command line.

Any configuration option that is passed from the command line will override the one specified inside the configuration file.

Using local configuration files

Specify Ansible-lint configuration in either .ansible-lint, .config/ansible-lint.yml, or .config/ansible-lint.yaml in your current working directory.

Note

If Ansible-lint cannot find a configuration file in the current directory it attempts to locate it in a parent directory. However Ansible-lint does not try to load configuration that is outside the git repository.

Specifying configuration files

Use the -c <filename> CLI flag with command line invocations of Ansible-lint, for example:

ansible-lint -c path/to/ansible-lint-dev.yml

Ansible-lint configuration

The following values are supported, and function identically to their CLI counterparts:

---
# .ansible-lint

profile: null # min, basic, moderate,safety, shared, production

# Allows dumping of results in SARIF format
# sarif_file: result.sarif

# exclude_paths included in this file are parsed relative to this file's location
# and not relative to the CWD of execution. CLI arguments passed to the --exclude
# option are parsed relative to the CWD of execution.
exclude_paths:
  - .cache/ # implicit unless exclude_paths is defined in config
  - test/fixtures/formatting-before/
  - test/fixtures/formatting-prettier/
# parseable: true
# quiet: true
# strict: true
# verbosity: 1

# Mock modules or roles in order to pass ansible-playbook --syntax-check
mock_modules:
  - zuul_return
  # note the foo.bar is invalid as being neither a module or a collection
  - fake_namespace.fake_collection.fake_module
  - fake_namespace.fake_collection.fake_module.fake_submodule
mock_roles:
  - mocked_role
  - author.role_name # old standalone galaxy role
  - fake_namespace.fake_collection.fake_role # role within a collection

# Enable checking of loop variable prefixes in roles
loop_var_prefix: "^(__|{role}_)"

# Enforce variable names to follow pattern below, in addition to Ansible own
# requirements, like avoiding python identifiers. To disable add `var-naming`
# to skip_list.
var_naming_pattern: "^[a-z_][a-z0-9_]*$"

use_default_rules: true
# Load custom rules from this specific folder
# rulesdir:
#   - ./rule/directory/

# Ansible-lint is able to recognize and load skip rules stored inside
# `.ansible-lint-ignore` (or `.config/ansible-lint-ignore.txt`) files.
# To skip a rule just enter filename and tag, like "playbook.yml package-latest"
# on a new line.
# Optionally you can add comments after the tag, prefixed by "#". We discourage
# the use of skip_list below because that will hide violations from the output.
# When putting ignores inside the ignore file, they are marked as ignored, but
# still visible, making it easier to address later.
skip_list:
  - skip_this_tag

# Ansible-lint does not automatically load rules that have the 'opt-in' tag.
# You must enable opt-in rules by listing each rule 'id' below.
enable_list:
  - args
  - empty-string-compare # opt-in
  - no-log-password # opt-in
  - no-same-owner # opt-in
  - name[prefix] # opt-in
  # add yaml here if you want to avoid ignoring yaml checks when yamllint
  # library is missing. Normally its absence just skips using that rule.
  - yaml
# Report only a subset of tags and fully ignore any others
# tags:
#   - jinja[spacing]

# Ansible-lint does not fail on warnings from the rules or tags listed below
warn_list:
  - skip_this_tag
  - experimental # experimental is included in the implicit list
  # - role-name
  # - yaml[document-start]  # you can also use sub-rule matches

# Some rules can transform files to fix (or make it easier to fix) identified
# errors. `ansible-lint --fix` will reformat YAML files and run these transforms.
# By default it will run all transforms (effectively `write_list: ["all"]`).
# You can disable running transforms by setting `write_list: ["none"]`.
# Or only enable a subset of rule transforms by listing rules/tags here.
# write_list:
#   - all

# Offline mode disables installation of requirements.yml and schema refreshing
offline: true

# Define required Ansible's variables to satisfy syntax check
extra_vars:
  foo: bar
  multiline_string_variable: |
    line1
    line2
  complex_variable: ":{;\t$()"

# Uncomment to enforce action validation with tasks, usually is not
# needed as Ansible syntax check also covers it.
# skip_action_validation: false

# List of additional kind:pattern to be added at the top of the default
# match list, first match determines the file kind.
kinds:
  # - playbook: "**/examples/*.{yml,yaml}"
  # - galaxy: "**/folder/galaxy.yml"
  # - tasks: "**/tasks/*.yml"
  # - vars: "**/vars/*.yml"
  # - meta: "**/meta/main.yml"
  - yaml: "**/*.yaml-too"

# List of additional collections to allow in only-builtins rule.
# only_builtins_allow_collections:
#   - example_ns.example_collection

# List of additions modules to allow in only-builtins rule.
# only_builtins_allow_modules:
#   - example_module

# Allow setting custom prefix for name[prefix] rule
task_name_prefix: "{stem} | "
# Complexity related settings

# Limit the depth of the nested blocks:
# max_block_depth: 20

Ignoring rules for entire files

Ansible-lint will load skip rules from an .ansible-lint-ignore or .config/ansible-lint-ignore.txt file that should reside adjacent to the config file. The file format is very simple, containing the filename and the rule to be ignored. It also supports comments starting with #.

.ansible-lint-ignore
# this is just a comment
playbook.yml package-latest # disable package-latest rule for playbook.yml
playbook.yml deprecated-module

The file can also be created by adding --generate-ignore to the command line. Keep in mind that this will override any existing file content.

Pre-commit setup

To use Ansible-lint with the pre-commit tool, add the following to the .pre-commit-config.yaml file in your local repository.

Do not confuse the pre-commit tool with the git hook feature that has the same name. While the pre-commit tool can also make use of git hooks, it does not require them and it does not install them by default.

pre-commit.ci is a hosted service that can run pre-commit for you on each change but you can also run the tool yourself using the CI of your choice.

Change rev: to either a commit sha or tag of Ansible-lint that contains .pre-commit-hooks.yaml.

---
ci:
  # This section is specific to pre-commit.ci, telling it to create a pull request
  # to update the linter version tag every month.
  autoupdate_schedule: monthly
  # If you have other Ansible collection dependencies (requirements.yml)
  # `pre-commit.ci` will not be able to install them because it runs in offline mode,
  # and you will need to tell it to skip the hook.
  # skip:
  #   - ansible-lint
repos:
- repo: https://github.com/ansible/ansible-lint
  rev: ... # put latest release tag from https://github.com/ansible/ansible-lint/releases/
  hooks:
    - id: ansible-lint
      # Uncomment if you need the full Ansible community bundle instead of ansible-core:
      # additional_dependencies:
      #   - ansible

Warning

pre-commit always uses python virtual environments. If you happen to use the Ansible package instead of just ansible-core you might be surprised to see that pre-commit is not able to find these collections, even if your local Ansible does. This is because they are installed inside a location that is not available to the virtual environment in which pre-commit hook is installed. In this case, you might want to uncomment the commented lines from the hook definition above, so the bundle will be installed.

You should note that collection installed into ~/.ansible are found by the hook.