Since we are moving to Ansible Collections, some things are changing. Now when you create your collection and update your collection Ansible Galaxy will no longer automatically discover your collection via a Webhook. Now for Galaxy to know about your collection you have to upload a tar.gz file that containers the result of the ansible-galaxy collection build command.
However, many of us may still want to automate that process, and with @geerlingguy‘s help I was able to fully automate the release process, not from just tagging a release, but creating a release as we would before. So how does this work?
Creating the Build Directory
First, we need to create the build/ directory and include a couple of files.
|
1 2 3 4 |
build ├── galaxy_deploy.yml └── templates └── galaxy.yml.j2 |
Instead of having a galaxy.yml file in our root, we will need to generate the file when we execute the playbook.
This is the galaxy_deploy.yml playbook.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
--- - hosts: localhost connection: local gather_facts: false vars: # This should be set via the command line at runtime. tag: "{{ github_tag.split('/')[-1] }}" pre_tasks: - name: Ensure the ANSIBLE_GALAXY_TOKEN environment variable is set. fail: msg: ANSIBLE_GALAXY_TOKEN is not set. when: "lookup('env','ANSIBLE_GALAXY_TOKEN') | length == 0" - name: Ensure the ~/.ansible directory exists. file: path: ~/.ansible state: directory - name: Write the Galaxy token to ~/.ansible/galaxy_token copy: content: | token: {{ lookup('env','ANSIBLE_GALAXY_TOKEN') }} dest: ~/.ansible/galaxy_token tasks: - name: Template out the galaxy.yml file. template: src: templates/galaxy.yml.j2 dest: ../galaxy.yml register: galaxy_yml - name: Build the collection. # noqa 503 command: > ansible-galaxy collection build chdir=../ when: galaxy_yml.changed - name: Publish the collection. # noqa 503 command: > ansible-galaxy collection publish ./ericsysmin-system-{{ tag }}.tar.gz chdir=../ when: galaxy_yml.changed |
You’ll then need to create a build/templates folder, and create the galaxy.yml.j2 file within the templates folder.
Edit the values to fit your Ansible Collection, the only var I use is {{ tag }} which will be used later on.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 |
### REQUIRED # The namespace of the collection. This can be a company/brand/organization or product namespace under which all # content lives. May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with # underscores or numbers and cannot contain consecutive underscores namespace: ericsysmin # The name of the collection. Has the same character restrictions as 'namespace' name: system # The version of the collection. Must be compatible with semantic versioning version: "{{ tag }}" # The path to the Markdown (.md) readme file. This path is relative to the root of the collection readme: README.md # A list of the collection's content authors. Can be just the name or in the format 'Full Name <email> (url) # @nicks:irc/im.site#channel' authors: - Eric Anderson (https://ericsysmin.com) ### OPTIONAL but strongly recommended # A short summary description of the collection description: Collection of System Administration Roles # Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only # accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file' # license: # - GPL-2.0-or-later # The path to the license file for the collection. This path is relative to the root of the collection. This key is # mutually exclusive with 'license' license_file: 'LICENSE' # A list of tags you want to associate with the collection for indexing/searching. A tag name has the same character # requirements as 'namespace' and 'name' tags: - system - chrony - epel - logrotate - ntp - remi_repo - selinux - rhel - ubuntu # Collections that this collection requires to be installed for it to be usable. The key of the dict is the # collection label 'namespace.name'. The value is a version range # L(specifiers,https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification). Multiple version # range specifiers can be set and are separated by ',' dependencies: {} # The URL of the originating SCM repository repository: https://github.com/ericsysmin/ansible-collection-system # The URL to any online docs documentation: https://github.com/ericsysmin/ansible-collection-system # The URL to the homepage of the collection/project homepage: https://github.com/ericsysmin/ansible-collection-system # The URL to the collection issue tracker issues: https://github.com/ericsysmin/ansible-collection-system/issues |
Ok, so now that we’ve created the build components now we need to do the automation part of this. I chose to use GitHub Actions again, as they are the recommended path for the repositories sitting at https://github.com/ansible-collections.
Configuring the GitHub Action Workflow
In your .github/workflows/ folder you’ll need to create a release workflow. To do this I used the following GitHub Actions Workflow YAML. I called it release.yml , and it sits at .github/workflows/release.yml this is an example of what you can use.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
name: "release" on: release: types: - created jobs: release: runs-on: ubuntu-18.04 env: ANSIBLE_GALAXY_TOKEN: ${{ secrets.ANSIBLE_GALAXY_TOKEN }} ANSIBLE_FORCE_COLOR: 1 steps: - name: Check out code uses: actions/checkout@v1 - name: Set up Python 3.8 uses: actions/setup-python@v1 with: python-version: 3.8 - name: Install dependencies run: | python -m pip install --upgrade pip pip install ansible - name: Run role test run: >- ansible-playbook -i 'localhost,' build/galaxy_deploy.yml -e "github_tag=${{ github.ref }}" |
Using the on value we are able to set the workflow to only execute when a release is created in GitHub. This will ensure we have a GitHub ref to be used against the playbook. It will also sync your Ansible Galaxy release with GitHub release actions.
|
1 2 3 4 |
on: release: types: - created |
If you noticed we have a key here that provides our Ansible Galaxy token ${{ secrets.ANSIBLE_GALAXY_TOKEN }} for us to use this token we need to get it from Ansible Galaxy, and add it to our repository secrets. You can find your key here https://galaxy.ansible.com/me/preferences under API Key.
Within the GitHub repo go to the Settings -> Secrets.
Then when on that page we will add a new secret and name it ANSIBLE_GALAXY_TOKEN
Now when the Workflow runs it will grab this secret from your GitHub and be able to authenticate to Ansible Galaxy.
This section tells GitHub Actions to only run this workflow when a release is created. That is done in the GitHub UI, just like you did in the past to release a new version of a role.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
steps: - name: Check out code uses: actions/checkout@v1 - name: Set up Python 3.8 uses: actions/setup-python@v1 with: python-version: 3.8 - name: Install dependencies run: | python -m pip install --upgrade pip pip install ansible - name: Run role test run: >- ansible-playbook -i 'localhost,' build/galaxy_deploy.yml -e "github_tag=${{ github.ref }}" |
This section:
- checks out the code
- configures python 3.8 on the host
- installs the latest version of python pip
- installs ansible
- then runs the playbook with the github.ref value from the GitHub Release action
Once this is done you will have the release version uploaded automatically to your Ansible Galaxy account.