Cookiecutter for Ansible Role

A cookiecutter for Ansible roles with:

• a requirements.txt file containing the required Python packages;
• initialized Molecule directory for testing;
• GitHub Actions workflow for running YAML Lint, Ansible Lint and Molecule for continuous integration;
• GitHub Actions workflow for publishing the role to Ansible Galaxy;
• a COPYING file containing the copyright license for the role; and
• a license notice at the top of each file.

Usage

Install the pip package manager for Python.

sudo apt install --yes python3-pip

Install the Cookiecutter package (preferably create a Python virtual environment beforehand).

pip install cookiecutter

Create a project skeleton for a new Ansible role.

cookiecutter gh:geoffreyvanwyk/cookiecutter-ansible-role

The command above will prompt for the namespace and name of the role, among other things, then it will create a directory within the current working directory, named after the role.

Change into the new directory, then install the required Python packages.

cd <new-role-directory>
pip install --requirement requirements.txt

If you have already installed the Docker Engine (if not, see Testing with Molecule section of the README below) and the Docker service is running:

sudo service docker status

You can now confirm that all Molecule tests pass at this stage.

molecule test

After this, you are ready to start building your Ansible role.

How to use Features

Testing with Molecule

To use Molecule, first install Docker Engine then run it as a service.

sudo service docker start

Publishing to Ansible Galaxy

To publish to Ansible Galaxy, create an account on it, copy your API key from the Preferences page of your Galaxy profile, then save it in the settings of your GitHub repository (Security > Secrets and variables > Actions > Secrets > Repository secrets) as GALAXY_API_KEY.

When you are ready to publish, add a Git tag to the last commit. The tag name must start with a v.

Contributing

To contribute to this repository, please use the Conventional Commits convention. It makes it easier to create change logs for new releases.

The commits are linted using Commit Lint whenever a pull request is made.

To have the Commit Lint check your commits locally as a commit-msg hook, run npm install after cloning this repository. If you are using Visual Studio Code, you can also install the Commit Lint extension recommended by this repository, to lint your commits as you write them in the Source Control panel of VS Code.

License

Copyright © 2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)

This file is part of Cookiecutter for Ansible role.

Cookiecutter for Ansible role is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Cookiecutter for Ansible role is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Cookiecutter for Ansible role. If not, see https://www.gnu.org/licenses/.