Ansible 101 - Linting

Using linting tools to ensure quality Ansible content.

• What is Linting?
• What is Ansible?
• When to use lint tools?
• Which linting tools are available?
• What features are available?
• Where to begin?
• Pipelines
  • Pre-Commit
  • Github Workflow Actions
  • BitBucket Action?
  • Azure DevOps Build Pipeline

What is Linting?

lint, or a linter, is a tool that analyzes source code to flag programming errors, bugs, stylistic errors, and suspicious constructs. The term originates from a Unix utility that examined C language source code.

lint-like tools have evolved to detect an even wider variety of suspicious constructs. They are especially useful for interpreted languages like JavaScript, Python and Ansible because such languages lack a compiling phase that displays a list of errors prior to execution. These tools generally perform static analysis of source code and produce information about:

• syntax issues
• unused variables
• calls to deprecated functions
• spacing and formatting conventions
• best practices

What is Ansible?

Ansible itself is not a language but rather a collection of concepts such as Playbooks, Modules, and so on. These concepts are implemented in different languages such as YAML or Python and we need to be aware of that before attempting to lint Ansible content. Below is a breakdown of some of the major concepts and related languages within Ansible.

Ansible Concept	Language	Category	More Info
Playbooks, Roles	YAML (1.2)	Data serialization language	https://yaml.org/spec/1.2/spec.html
Modules, Plugins	Python	Interpreted language	https://www.python.org/
Templates	Jinja2	Web template engine language	http://jinja.pocoo.org/docs/2.10/
Static Inventory	X	Similar to INI file format often used for config files	https://en.wikipedia.org/wiki/INI_file
Other Files	X	JSON format, XML, etc.

When to use lint tools?

Linting is performed during the development phase and should be used as early as possible. Below lists some potential areas to use linting:

• Developer Writes Code and linting can be dynamically triggered to test recently saved changes either through an IDE or some other editor.
• Developer Commits Code Locally using version control process and linting can be triggered to not only check code quality but prevent the commit if errors exist.
• Developer Pushes Code to Remote Repository can automatically trigger an action to lint the code and provide immediate results to the owners of the repository.
• Create Pull Request can automatically trigger an action to lint the changes in the PR and provide that feedback before approval
• Merge Code can automatically trigger an action to lint the integrated code in a specific branch, which is useful for CI pipelines.

Which linting tools are available?

• ansible-lint
• yamllint
• jinjalint
• jinja2-lint
• flake8

What features are available?

TODO: Check my table from slidedeck for what ansible-lint can do. Provide explanations for these features.

• Supports customization using a configuration file
• Supports producing errors and warnings
  • Errors enforce standards by preventing progress until issues are fixed
  • Warnings recommend standards but does not prevent progress
• Supports offline mode, which disables installation of requirements.yml
• Supports enable or disable color output
• Supports using Pre-Commit
• Rules
  • Provides predefined rules
  • Offers easy to customize rules
  • Supports false positives, which allows specific code blocks or files to be marked as excluded from linting for various reasons
  • Supports adding new custom rules
  • Supports using completely different set of rules
  • Supports skipping one or more rules
  • Supports warning about rules (instead of errors)
• Supports Ansible concepts
  • Inventory, both in INI and YAML format
  • Playbook
  • Role
  • Jinja2 Templates
  • Python for modules and plugins

Where to begin?

• Nobody cares about WARNINGs. We only need to define the rules to enforce and hence, those that we don’t care about. Nobody looks at warnings and says “Oh good idea, I’ll do that extra work and fix that.” Typically it’s only rules that prevent you from committing the code or approving the PR that tend to be fixed.

• Pre-Commit, pre-commit offers linting for all areas that are even non-ansible concepts. For example, you might want to prevent large files being added to the repository - use the check-added-large-files pre-commit hook.
• Pre-Commit Hooks, can add functionality to pre-commit to check on various aspects of your repository. Some examples:
  • check-added-large-files - Prevent giant files from being committed
  • detect-private-key - Detects the presence of private keys
  • flake8 - Run flake8 to lint your python files
  • trailing-whitespace - Trims trailing whitespace
  • enforce only yml extension and not yaml extension
  • Ensure branch name matches JIRA ticket number
  • prettier - make code pretty (e.g. https://prettier.io)
  • and more (https://github.com/pre-commit/pre-commit-hooks)
• Repositories, Learn to use and manage the repositories that allow you to store and collaborate on your project’s code.
• About Protected Branches, You can protect important branches by setting branch protection rules, which define whether collaborators can delete or force push to the branch and set requirements for any pushes to the branch, such as passing status checks or a linear commit history.

Pipelines

The following sections cover quickly how you can leverage pipelines to automate and enforce the use of linting to ensure code quality and standards.

Pre-Commit

Github Workflow Actions

https://ansible-lint.readthedocs.io/en/latest/usage.html#ci-cd

BitBucket Action?

Example repository: https://bitbucket.org/ansiblejunky/ansible-lint-demo/src/master/ Requires bitbucket-pipelines.yml file in root folder: https://bitbucket.org/ansiblejunky/ansible-lint-demo/src/master/bitbucket-pipelines.yml

Azure DevOps Build Pipeline