CookieCutter Ansible Role

Awesome Cookiecutter template for creating Ansible Roles.

Table of Contents

• Primary Features
  • Ansible
  • Development
  • GitHub
• Usage
• Generic Features of this 🍪
  • Documentation
  • Development
  • GitHub

Primary Features

Ansible

• Includes all Files and Folders expected to be found in an Ansible Role.

• Every Ansible file starts with a conventional comment containing the name of the role and the purpose of the file

• Includes Ansible Galaxy meta.yml

• Includes Molecule Converge Definition with Docker and systemd-enabled Images

• Uses single vars/main.yml paradigm instead of per-distribution file and include tasks paradigm, as shown below:

  _rolename__somevar:
    Debian: ""
    Debian_10: ""
    RedHat: ""
  
  rolename__somevar: "{{
    _rolename__somevar[ansible_distribution ~ '_' ~ ansible_distribution_major_version]|default(
    _rolename__somevar[ansible_os_family ~ '_' ~ ansible_distribution_major_version])|default(
    _rolename__somevar[ansible_distribution])|default(
    _rolename__somevar[ansible_os_family])|default(
    _rolename__somevar['default']) }}"

Development

• Includes a Visual Studio Code Development Container Definition.

GitHub

• Includes a Continuous GitHub Workflow to yamllint / ansiblelint all files

• Includes a Continuous GitHub Workflow to run molecule test’s on a matrix of different distributions (with systemd support) and different Ansible versions

• Includes a GitHub Workflow to release to Ansible Galaxy

  ℹ️	Requires a GALAXY_API_KEY secret present in the GitHub repository or organization!

Usage

First, get Cruft. It’s a tool built in Cookiecutter that will allow you to keep up-to-date with the changes made to this cookiecutter.

$ python3 -m pip install cruft

Now run it against this repo:

$ cruft create https://github.com/JonasPammer/cookiecutter-ansible-role.git

Answer the prompts with your own desired options.

Enter the project and take a look around (replace "my-github-action" with your project slug):

$ cd my-github-action
~/my-github-action$ ls

Create a git repo and push it there (replace "YourGitHubName" with your github profile name and "my-github-action" with your project slug):

~/my-github-action$ git init
~/my-github-action$ git add .
~/my-github-action$ git commit -m "chore: create from cookiecutter"
~/my-github-action$ git remote add origin git@github.com:YourGitHubName/my-github-action.git
~/my-github-action$ git push -u origin master

Now take a look at your repo. Don’t forget to carefully look at the generated README - It contains all relevant Development Documentation.

Awesome, right?

ℹ️	This CookieCutter does not configure your GitHub Repository. Please read the notes found in this README and perform the documented manual steps (e.g., Creating GitHub Action Secrets).

Generic Features of this 🍪

I maintain several CookieCutter’s. Many of them share a similiar set of boilerplate files. You will find this section to be the same in most of them.

Documentation

• Includes an Awesome README

  ℹ️

  Because github/markup#1095 (support include directives for other asciidoc files) is still not fixed, the following measures were taken: README.orig.adoc is the actual README that must be edited. A GitHub Workflow takes care of generating the actual README.adoc using the official tool ascidoctor-reducer. [optional] The README also exists as an automatically published GitHub Page, of which the HTML was generated by Asciidoctor (= done right). ℹ️ For this to work, you need to activate the Pages feature on a per-repository basis. To do so, go to the Settings page of your GitHub repository. Under Pages / Source, select [GitHub Actions], and click Save.

• Includes a Beginner-Friendly Development Documentation file

• Includes a Beginner-Friendly generic Contribution Documentation file, inspired by Auth0’s Open Source Template.

• Includes ability to select and generate any of the Licenses found on https://choosealicense.com/licenses/.

• Includes a generic security policy file that states that only the current major version of the project is actively supported with patches and that problems should be sent to the e-mail address specified when the cookiecutter was created. The file also contains a template that may be used for such inqueries.

Development

• Assumes MIT License.

• Changelog is assumed to be managed through the use of GitHub Releases.

• Includes numerous pre-commit hooks to automatically find linting issues, format your files, and find common issues of version control and source code

• Includes a very much standard yamllint configuration (enforced through pre-commit and checked by CI)

• Assumes enforcement of Conventional Commit (checked by a pre-commit hook if activated)

  ❗	The resulting projects mentions that this is completely optional for casual contributors, as it is assumed that pull requests are squash-merged by maintainers.

• Includes a exhaustive .gitignore file generated by gitignore.io

• Includes a copy of the Contributor Covenant Code of Conduct as generated automatically by GitHub.

GitHub

ℹ️	The resulting projects mentions that pre-commit installation is optional, as it is assumed that the project is included in your pre-commit.ci account projects.

• Includes a .gitattributes file, ensuring LF line endings

• Includes GitHub Issue Form Templates for filing bug reports and feature requests using HTML forms

• Includes a GitHub Pull Request Template

• Includes a GitHub Workflow to denote size of pull requests by automagically labelling them

• Includes an pretty standard Renovate configuration file for dependency update automation (similiar to dependabot, but better).

  ℹ️	To enable Renovate, you need to enable it for your repositories, e.g. by using the recommended Way of installing the Renovate GitHub App to your GitHub profile (for free)!

• Includes a GitHub Workflow to declaratively manage labels

  • The predefined labels definition is inspired by the kubernetes project