Ansible Role Template

This repository provides a base scaffolding template to use as a quick start of all Ansible roles at @Appsilon. Includes best practices that should always be used, like linter, tests, CI, etc.

How to Use

1. Click "Use this template" to create a new repository from it.
2. Update ./meta/main.yml with updated repository and role names.
3. Update ./role_README.md with updated to repository and role name.
4. Rename ./role_README.md to README.md.
5. Start coding! You're free to change anything.

Development

Dependencies

To execute tests locally, it is necessary to install the following dependencies:

• Python
• Molecule

Preparing the Environment

Create a Python environment:

python3 -m venv .venv

Activate the environment:

source .venv/bin/activate

Install molecule (and its dependencies) inside the environment:

python3 -m pip install -r requirements.txt

Running

molecule test

To perform quick test after some modification:

molecule create
molecule converge
molecule verify

To log into the running instance for troubleshooting purposes:

molecule login

At the end of the test, destroy the environment:

molecule destroy

Validation, Linters and Pull-Requests

We want to provide high quality code. For this reason we are using several pre-commit hooks and GitHub Actions workflow. A pull-request to the main branch will trigger these validations and lints automatically. Please check your code before you will create pull-requests.

Before you can run hooks, you need to have the pre-commit installed.

pip install pre-commit
pre-commit install

If you are going to enforce Conventional Commits commit message style on the title you will also need to install gitlint.

pip install gitlint

You then need to install the pre-commit hook like so:

pre-commit install --hook-type commit-msg

It's important that you run pre-commit install --hook-type commit-msg, even if you've already used pre-commit install before. pre-commit install does not install commit-msg hooks by default!

To manually trigger gitlint using pre-commit for your last commit message, use the following command:

pre-commit run gitlint --hook-stage commit-msg --commit-msg-filename .git/COMMIT_EDITMSG

In case you want to change gitlint's behavior, you should either use a .gitlint file (see Configuration) or modify the gitlint invocation in your .pre-commit-config.yaml file like so:

-   repo: https://github.com/jorisroovers/gitlint
    rev:  # Fill in a tag / sha here
    hooks:
    -   id: gitlint
        args: [--contrib=CT1, --msg-filename]

See pre-commit documentation and GitHub Actions documentation for further details.