README.md

ansible_galaxy_collection

Deploy a Collection to Ansible Galaxy.

Requirements

This action expects to be run from a repository with certain met conditions.

1. The repository contains a valid Ansible Galaxy Collection, meaning it minimally contains a galaxy.yml file and a README.md.
2. The repository has a top-level meta directory with the file runtime.yml minimally containing the key requires_ansible, which is required by Ansible Galaxy.

An example workflow using this action can be found here and in the tests.

Inputs

api_key

Required: Ansible Galaxy API key.

This should be protected as a secret in your workflow. See Creating and Using Secrets Encrypted Variables.

collection_dir

Default: ./

The directory in which the Ansible Collection is stored. This defaults to the project root.

Only change this if your Collection is not stored in your project root.

galaxy_version

Semver-compatible string: 1, 1.1, 1.1.1, 1.1.1-alpha

Dynamically inject a semver-compatible version into your galaxy.yml file.

publish

New in v2.5.0

Default: true

If you want to build a collection archive file but do not want to publish it to Ansible Galaxy, you can disable the publishing by setting this parameter to false.

The Action will create a collection archive file in the default ansible-galaxy collection format: <namespace-from-galaxy-yml>-<name-from-galaxy-yml>-<semver-version>.tar.gz.

e.g. artis3n-mycollection-1.0.0.tar.gz

build

New in v2.5.0

Default: true

If you already have a built collection archive file you can disable this Action from building one by setting this parameter to false. This will publish any existing collection archive to Ansible Galaxy.

Note that the Action expects the built archive to exist in the root of the collection_dir directory. By default, that is the project root.

The Action also expects the built archive to be named in the default ansible-galaxy collection format: <namespace-from-galaxy-yml>-<name-from-galaxy-yml>-<semver-version>.tar.gz.

e.g. artis3n-mycollection-1.0.0.tar.gz

galaxy_config_file (Deprecated)

Default: galaxy.yml

A collection must have a galaxy.yml file that contains the necessary information to build a collection artifact. Defaults to "galaxy.yml" in the collection_dir.

This parameter is deprecated as Ansible Galaxy requires the file to be named galaxy.yml and to exist in the root of your Collection. Use collection_dir to specify a non-root directory for your Collection.

Example Usage

Minimal complete example:

---
name: Deploy Collection

# Trigger the workflow however you prefer
on:
  release:
    types:
      - published

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build and Deploy Collection
        uses: artis3n/ansible_galaxy_collection@v2
        with:
          api_key: '${{ secrets.GALAXY_API_KEY }}'

Pass in galaxy.yml version as an input parameter:

- name: Get the version name from the tags
  run: echo "RELEASE_VERSION=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_ENV

- name: Injecting a dynamic Collection version
  uses: artis3n/ansible_galaxy_collection@v2
  with:
    api_key: '${{ secrets.GALAXY_API_KEY }}'
    galaxy_version: '${{ env.RELEASE_VERSION }}'

If your Collection root is not in your repo root:

- name: When the Collection is not in the project root
  uses: artis3n/ansible_galaxy_collection@v2
  with:
    api_key: '${{ secrets.GALAXY_API_KEY }}'
    collection_dir: 'src/my_collection'

To build a collection without publishing it to Ansible Galaxy:

- name: Build Collection
  uses: artis3n/ansible_galaxy_collection@v2
  with:
    api_key: '${{ secrets.GALAXY_API_KEY }}'
    publish: false

If you already have a collection archive built and merely want to publish it to Ansible Galaxy without building a new one:

- name: Publish Collection
  uses: artis3n/ansible_galaxy_collection@v2
  with:
    api_key: '${{ secrets.GALAXY_API_KEY }}'
    build: false

Exit Codes

• 0: Ok
• 1: DeployFailed
  • The Action attempted to deploy to Ansible Galaxy, but failed. There will be details of the error from Ansible Galaxy recorded at the end of the action's logs.
• 2: ValidationFailed
  • One or more user-supplied input parameters were invalid. See the error message for validation details.
• 3: BuildFailed
  • The action encountered an error performing ansible-galaxy collection build. Details should be available in the action details.
• 4: PublishFailed
  • The action encountered an error performing ansible-galaxy collection publish. Details should be available in the action details.