Configuring

Configuration File

Ansible-lint supports local configuration via a .ansible-lint configuration file. Ansible-lint checks the working directory for the presence of this file and applies any configuration found there. The configuration file location can also be overridden via the -c path/to/file CLI flag.

When configuration file is not found in current directory, the tool will try to look for one in parent directories but it will not go outside current git repository.

If a value is provided on both the command line and via a config file, the values will be merged (if a list like exclude_paths), or the True value will be preferred, in the case of something like quiet.

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

# .ansible-lint
exclude_paths:
- .cache/  # implicit unless exclude_paths is defined in config
- .github/
# parseable: true
# quiet: 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/

# This makes linter to fully ignore rules/tags listed below
skip_list:
  - skip_this_tag
  - git-latest

# Any rule that has the 'opt-in' tag will not be loaded unless its 'id' is
# mentioned in the enable_list:
enable_list:
  - fqcn-builtins  # opt-in
  - no-log-password  # opt-in
  - no-same-owner  # 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:
#   - var-spacing

# This makes the linter display but not fail for rules/tags listed below:
warn_list:
  - skip_this_tag
  - git-latest
  - experimental  # experimental is included in the implicit list
  # - role-name

# Offline mode disables installation of requirements.yml
offline: false

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

Pre-commit Setup

To use ansible-lint with pre-commit, just add the following to your local repo’s .pre-commit-config.yaml file. Make sure to change rev: to be either a git commit sha or tag of ansible-lint containing hooks.yaml.

- repo: https://github.com/ansible-community/ansible-lint.git
  rev: ...  # put latest release tag from https://github.com/ansible-community/ansible-lint/releases/
  hooks:
    - id: ansible-lint
      files: \.(yaml|yml)$