This template standardizes and expedites the process of publishing easily consumed, automatically tested Ansible roles.
It extends the scaffolding provided by ansible-galaxy init to include the following:
- Multi-distro testing on Travis CI (currently supports CentOS 6+ and Ubuntu 12.04+)
- CyVerse documentation conventions (e.g. variables table)
- CyVerse license file
These instructions are based on https://galaxy.ansible.com/intro#create-role and http://docs.ansible.com/ansible/galaxy.html; you don't need to read those but they are good references.
Also, you don't need to use ansible-galaxy init if you are using this template.
Naming convention is "ansible-purpose-of-role" in the cyverse-ansible Github organization.
Clone this repo locally, rename the folder according to your role, and delete the .git folder (it will become a new repository).
Build the role functionality into the folder structure, or migrate an existing role into it.
Populate section 3 of .travis.yml with tests which confirm that your role produces the desired effect on a target system. This is not strictly necessary but is strongly encouraged.
Fill out role-README.md, which will become README.md.
Replace "Role Name" on line 1 with the name of your role, matching the name of your git repository but dropping the "ansible-" prefix, e.g. "purpose-of-role".
In order for the badges to work, you'll need to replace their image and link URLs.
Fill out any needed variables in a table, similar to how Ansible's core modules are documented (example).
Also, fill out meta/main.yml. What you enter here will be populated on Ansible Galaxy.
- Delete any empty/unused boilerplate folders and YAML files.
- Search the entire role for "role-template" and ensure you have changed its name everywhere.
- Delete this file (readme.md) and rename role-README.md to README.md. (Ansible Galaxy requires the filename to be uppercase.)
Create a new Git repo in CyVerse-Ansible. git init the role locally, commit, and push to GitHub. Don't forget to add the .travis.yml dotfile, which git add * doesn't include automatically.
If you do not have one already, create a Travis CI account and follow their instructions to link your GitHub account. Browse to your profile page, click the "sync" button, and enable the new repository in Travis CI.
If you do not have one already, create an Ansible Galaxy account linked to your GitHub account.
Go to "My Roles" and click the refresh button, your new role repository should appear. Turn on the switch.
Consumers of this role will want to pin their dependency on this role to a specific version. ansible-galaxy uses git tags to allow users to specify a version. See http://docs.ansible.com/ansible/latest/galaxy.html#installing-multiple-roles-from-a-file. Please use the SemVer protocol.
Any subsequent commits that you push to your GitHub repo should automatically trigger a build in Travis CI, and import the role into Galaxy when a build completes with passing status.
If you want to run an import manually, browse to my imports on Galaxy. The import process has built-in YAML linting, and if there are any issues preventing a successful import then you will see an error message here.
- http://www.jeffgeerling.com/blog/testing-ansible-roles-travis-ci-github
- This tutorial was a large influence on the structure and design of this template.