This topic describes how to use the default Ansible Lint rules, as well as how to create and use custom rules.

Specifying Rules at Runtime

By default, ansible-lint uses the rules found in ansible-lint/lib/ansiblelint/rules. To override this behavior and use a custom set of rules, use the -r /path/to/custom-rules option to provide a directory path containing the custom rules. For multiple rule sets, pass multiple -r options.

It’s also possilbe to use the default rules, plus custom rules. This can be done by passing the -R to indicate that the deault rules are to be used, along with one or more -r options.

Using Tags to Include Rules

Each rule has an associated set of one or more tags. To view the list of tags for each available rule, use the -T option.

The following shows the available tags in an example set of rules, and the rules associated with each tag:

$ ansible-lint -v -T

behaviour ['[ANSIBLE0016]']
bug ['[ANSIBLE0014]']
deprecated ['[ANSIBLE0015]', '[ANSIBLE0008]', '[ANSIBLE0018]', '[ANSIBLE0019]']
formatting ['[ANSIBLE0015]', '[ANSIBLE0002]', '[ANSIBLE0009]']
idempotency ['[ANSIBLE0012]']
oddity ['[ANSIBLE0017]']
readability ['[ANSIBLE0011]']
repeatability ['[ANSIBLE0004]', '[ANSIBLE0010]', '[ANSIBLE0005]']
resources ['[ANSIBLE0007]', '[ANSIBLE0006]']
safety ['[ANSIBLE0013]']

To run just the idempotency rules, for example, run the following:

$ ansible-lint -t idempotency playbook.yml

Excluding Rules

To exclude rules from the available set of rules, use the -x SKIP_LIST option. For example, the following runs all of the rules except those with the tags readability and safety:

$ ansible-lint -x readability,safety playbook.yml

It’s also possible to skip specific rules by passing the rule ID. For example, the following excludes rule ANSIBLE0011:

$ ansible-lint -x ANSIBLE0011 playbook.yml

False Positives: Skipping Rules

Some rules are a bit of a rule of thumb. Advanced git, yum or apt usage, for example, is typically difficult to achieve through the modules. In this case, you should mark the task so that warnings aren’t produced.

To skip a specific rule for a specific task, inside your ansible yaml add # noqa [rule_id] at the end of the line. If the rule is task-based (most are), add at the end of any line in the task. You can skip multiple rules via a space-separated list.

- name: this would typically fire GitHasVersionRule 401 and BecomeUserWithoutBecomeRule 501
  become_user: alice  # noqa 401 501
  git: src=/path/to/git/repo dest=checkout

If the rule is line-based, # noqa [rule_id] must be at the end of the particular line to be skipped

- name: this would typically fire LineTooLongRule 204 and VariableHasSpacesRule 206
    url:  # noqa 204
    dest: "{{dest_proj_path}}/foo.conf"  # noqa 206

It’s also a good practice to comment the reasons why a task is being skipped.

If you want skip running a rule entirely, you can use either:

A less-preferred method of skipping is to skip all task-based rules for a task (this does not skip line-based rules). There are two mechanisms for this: the skip_ansible_lint tag works with all tasks, and the warn parameter works with the command or shell modules only. Examples:

- name: this would typically fire CommandsInsteadOfArgumentRule 302
  command: warn=no chmod 644 X

- name: this would typically fire CommandsInsteadOfModuleRule 303
  command: git pull --rebase
    warn: False

- name: this would typically fire GitHasVersionRule 401
  git: src=/path/to/git/repo dest=checkout
  - skip_ansible_lint

Creating Custom Rules

Rules are described using a class file per rule. Default rules are named, etc.

Each rule definition should have the following:

  • ID: A unique identifier
  • Short description: Brief description of the rule
  • Description: Behaviour the rule is looking for
  • Tags: one or more tags that may be used to include or exclude the rule
  • At least one of the following methods:
    • match that takes a line and returns None or False, if the line doesn’t match the test, and True or a custom message, when it does. (This allows one rule to test multiple behaviours - see e.g. the CommandsInsteadOfModulesRule.)
    • matchtask that operates on a single task or handler, such that tasks get standardized to always contain a module key and module_arguments key. Other common task modifiers, such as when, with_items, etc., are also available as keys, if present in the task.

An example rule using match is:

from ansiblelint import AnsibleLintRule

class DeprecatedVariableRule(AnsibleLintRule):

    id = 'ANSIBLE0001'
    shortdesc = 'Deprecated variable declarations'
    description = 'Check for lines that have old style ${var} ' + \
    tags = { 'deprecated' }

    def match(self, file, line):
        return '${' in line

An example rule using matchtask is:

import ansiblelint.utils
from ansiblelint import AnsibleLintRule

class TaskHasTag(AnsibleLintRule):
    id = 'ANSIBLE0008'
    shortdesc = 'Tasks must have tag'
    description = 'Tasks must have tag'
    tags = ['productivity']

    def matchtask(self, file, task):
        # If the task include another task or make the playbook fail
        # Don't force to have a tag
        if not set(task.keys()).isdisjoint(['include','fail']):
            return False

        # Task should have tags
        if not task.has_key('tags'):
              return True

    return False

The task argument to matchtask contains a number of keys - the critical one is action. The value of task[‘action’] contains the module being used, and the arguments passed, both as key-value pairs and a list of other arguments (e.g. the command used with shell).

In ansible-lint 2.0.0, task[‘action’][‘args’] was renamed task[‘action’][‘module_arguments’] to avoid a clash when a module actually takes args as a parameter key (e.g. ec2_tag)

In ansible-lint 3.0.0 task[‘action’][‘module’] was renamed task[‘action’][‘__ansible_module__’] to avoid a clash when a module take module as an argument. As a precaution, task[‘action’][‘module_arguments’] was renamed task[‘action’][‘__ansible_arguments__’].