README

Opinionated blueprints for ansible-galaxy role|collection init.

Ansible Skeletons help you start new roles and collections with a shared structure for tasks, metadata and tests.

The skeletons follow these style guides:

• foundata: Ansible style guide
• Red Hat’s Coding Style Good Practices for Ansible
• Best Practices of the Ansible User guide

⭐ Found this useful? Support open-source and star this project:

Features

• Configuration for ansible-lint and Molecule (using Containers via Podman and/or VMs via libvirt).
• Separate files for OS-specific variables and tasks.
• Changelog conventions and release-note helpers.
• A common project structure and defaults for new roles and collections.

Examples

Some collections built using these skeletons:

• foundata.acmesh:
  • GitHub: https://github.com/foundata/ansible-collection-acmesh
  • Galaxy: https://galaxy.ansible.com/ui/repo/published/foundata/acmesh/
• foundata.sshd:
  • GitHub: https://github.com/foundata/ansible-collection-sshd
  • Galaxy: https://galaxy.ansible.com/ui/repo/published/foundata/sshd/
• foundata.postfix:
  • GitHub: https://github.com/foundata/ansible-collection-postfix
  • Galaxy: https://galaxy.ansible.com/ui/repo/published/foundata/postfix/

Usage

1. Clone this repository and check out the latest release:

   ## Get the version number of the latest release
   version="$(curl -s -L https://api.github.com/repos/foundata/ansible-skeletons/releases/latest | jq -r '.tag_name' | sed -e 's/^v//g')"
   printf '%s\n' "${version}"
   
   ## Clone and check out the latest release (you can switch versions anytime using "git checkout vX.Y.Z")
   git clone https://github.com/foundata/ansible-skeletons.git -b "v${version}"
   

   
   

2. Use ansible-galaxy to initialize a new collection or standalone role. Provide the skeleton path and a name for the new resource. Pass any variable values you want to override, or use the defaults.
   Examples:

   ## Ensure ansible-galaxy is available and navigate to the cloned repository from step one
   ansible-galaxy --version
   cd ./path/to/ansible-skeletons
   
   ## Create a new collection called "namespace.new_collection" based on the "collection_default" skeleton
   ## Syntax: ansible-galaxy collection init --collection-skeleton <path> <extra variables> <name of the new collection including namespace>
   ansible-galaxy collection init \
      --collection-skeleton "./collection_default" \
      --extra-var '{"authors": ["FIXME User <user@example.com>"]}' \
      --extra-var "company='FIXME your organization'" \
      --extra-var "description='Manage FIXME.'" \
      --extra-var "repository='https://FIXME.example.com/repo/'" \
      --extra-var "issues='https://FIXME.example.com/repo/issues/'" \
      --extra-var "homepage='https://FIXME.example.com'" \
      --extra-var "min_ansible_version='2.16.0'" \
      --extra-var "version='0.1.0'" \
      "namespace.new_collection"
   
   ## Create a new stand-alone role called "new_role" based on the "role_default" skeleton
   ## Syntax: ansible-galaxy role init --collection-skeleton <path> <extra variables> <name of the new role>
   ansible-galaxy role init \
      --role-skeleton "./role_default" \
      --extra-var "author='FIXME User <user@example.com>'" \
      --extra-var "company='FIXME your organization'" \
      --extra-var "description='Manage FIXME.'" \
      --extra-var "repository_url='https://FIXME.example.com/repo/'" \
      --extra-var "issue_tracker_url='https://FIXME.example.com/repo/issues/'" \
      --extra-var "homepage_url='https://FIXME.example.com'" \
      --extra-var "min_ansible_version='2.16.0'" \
      "new_role"
   

   Notes:

   • Names of namespaces, collections or roles must follow some rules and should consist of a-z, 0-9 and _ only.
   • Adapt the directory name of the --[collection|role]-skeleton parameter value to use a skeleton other than [collection|role_]default. The available skeletons are described below.

3. Follow the instructions in the generated FIXME.md file to adapt the collection or standalone role to your project.

Provided skeletons

Each skeleton has its own subdirectory. The source files contain Jinja expressions that ansible-galaxy [collection|role] renders when generating a project.

collection_default

A skeleton for packaging and shipping a run role in an Ansible collection. It includes:

• Init tasks to check the environment and usage:
  • Role argument validation
  • Check for minimum Ansible version and supported operating systems / platform.
  • Automatic gathering of role-specific facts (useful with gather_facts: false)
  • Automatic search and include for platform-specific variables.
• Separation of logical task groups, automatic include for platform-specific tasks.
• Passes ansible-lint --profile production --strict.
• antsibull-changelog support.
• Molecule support with a default scenario using Podman and several integration test targets.

role_default

A skeleton for standalone Ansible roles. It includes:

• Init tasks to check the environment and usage:
  • Role argument validation
  • Check for minimum Ansible version and supported operating systems / platform.
  • Automatic gathering of role-specific facts (useful with gather_facts: false)
  • Automatic search and include for platform-specific variables.
• Separation of logical task groups, automatic include for platform-specific tasks.
• Passes ansible-lint --profile production --strict.
• Molecule support with a default scenario using Podman and several integration test targets.

Compatibility

The release gate tests rendering and role execution with these controller combinations, using the exact dependency versions recorded in uv.lock:

The matrix is defined in pyproject.toml; see Development: Testing for repeatable commands and infrastructure coverage. It is reviewed against the upstream support matrix.

Older Ansible core versions from 2.16 may work, but are outside the required release matrix. Historical manual checks included core 2.18. The development helpers require Python 3.12 or newer; consumers only need Ansible and its supported Python runtime.

The following versions are known to be problematic:

• ansible-galaxy [core 2.16.4] (“ERROR! Invalid collection name” when passing authors as extra-var)

Contributing

See CONTRIBUTING.md if you want to get involved.

The maintainers use the skeletons daily and continue to maintain them, even during periods with few repository updates.

Licensing, copyright

Copyright (c) 2020, 2023-2026 foundata GmbH (https://foundata.com)

This project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: GPL-3.0-or-later), see LICENSES/GPL-3.0-or-later.txt for the full text.

The REUSE.toml file provides detailed licensing and copyright information in a human- and machine-readable format. This includes parts that may be subject to different licensing or usage terms, such as third-party components. The repository conforms to the REUSE specification. You can use reuse spdx to create a SPDX software bill of materials (SBOM).

Trademarks

• Red Hat® is a trademark of Red Hat, Inc., registered in the US and other countries.
• Ansible® is a trademark of Red Hat, Inc., registered in the US and other countries.

Their use here is purely descriptive and does not imply any affiliation with or endorsement by the trademark holders.

Author information

This project was created and is maintained by foundata. If you like it, you might buy us a coffee.

The Ansible Skeletons project is not associated with Red Hat nor the Ansible project.