Opinionated blueprints for ansible-galaxy role|collection init
Ansible Skeletons help you start new roles and collections with a clean, consistent, and proven structure. Focus immediately on logic instead of boilerplate.
All skeletons follow several guidelines and best practices:
- 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
- Examples
- Usage
- Description of provided skeletons
- Compatibility
- Contributing
- Licensing, copyright
- Author information
Main features:
- Sensible defaults – metadata, version checks, and directory structures already configured.
- Linting and testing built-in – ready for
ansible-lintand Molecule - Platform-aware design – clear separation for OS-specific variables and tasks.
- Changelog tooling – conventions and helpers for transparent release notes.
- Reproducible structure - faster bootstrapping, fewer style debates. Focus on automation logic instead of boilerplate.
Some collections built using these skeletons:
foundata.acmesh:foundata.sshd:foundata.postfix:
Check their project structures for inspiration and reference.
- 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}"
- Use
ansible-galaxyto initialize a new collection or stand-alone role. Provide the path to the desired skeleton, along with any necessary variable values (or letansible-galaxyuse default values), and specify a name for your new resource.
Examples:Additional Notes:# 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 <[email protected]>"]}' \ --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 <[email protected]>'" \ --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"
- Names of namespaces, collections or roles must follow some rules and should consist of
a-z,0-9and_only. - Adapt the directory name of the
--[collection|role]-skeletonparameter value if you want to use another skeleton than[collection|role_]default. You can find a description of the available skeletons below.
- Names of namespaces, collections or roles must follow some rules and should consist of
- Each created collection or stand-alone role includes a
FIXME.mdfile in its root directory with further instructions about what to change to your needs.
The following list provides an overview of the available skeletons. You can also explore the subdirectories of this repository to examine their code. However, keep in mind that some parts may be difficult to read, as they contain Jinja code. This Jinja code is processed by ansible-galaxy [collection|role] with it's templating to generate the final files.
A general purpose skeleton to create new Ansible collection for package and ship a run-role. Main features:
- 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-changelogsupport.- Molecule support with a default scenario using Podman and several integration test targets.
A general purpose skeleton to create new Ansible stand-alone role. Main features:
- 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.
The skeletons are compatible with all supported versions of ansible-galaxy and ansible that are not end-of-life and still receive patches. While older versions should also work as long as ansible-core is >= v2.16, we no might not explicitly test them.
The skeletons were explicitly tested with ansible-galaxy from the following ansible versions (descending order):
ansible-galaxy 2.19ansible-galaxy [core 2.19.2]
ansible-galaxy 2.18ansible-galaxy [core 2.18.9]ansible-galaxy [core 2.18.8]ansible-galaxy [core 2.18.4]ansible-galaxy [core 2.18.3]ansible-galaxy [core 2.18.2]ansible-galaxy [core 2.18.1]
The following versions are known to be problematic:
ansible-galaxy [core 2.16.4]("ERROR! Invalid collection name" when passingauthorsas extra-var)
See CONTRIBUTING.md if you want to get involved.
This project's functionality is mature, so there might be little activity on the repository in the future. Don't get fooled by this, the project is under active maintenance and used on daily basis by the maintainers.
Copyright (c) 2020, 2023-2025 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).
- 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.
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.