A composite GitHub Action that publishes an Ansible collection or role to Ansible Galaxy. Installs Python and Ansible, then either runs ansible-galaxy collection build && publish (collection mode) or ansible-galaxy role import (role mode). Supports dry_run for CI validation without a live API key, and uploads the built tarball as a workflow artifact in dry-run mode for manual inspection.
- One action for both publish paths: collection (
build+publish) and role (import) — selected via a singletypeinput - Unified
namespace+nameinput pair for both modes (no mode-specific flags) dry_run: truevalidates inputs and — for collections — still builds the tarball and uploads it as a workflow artifact, without hitting Galaxy (ideal for pull-request CI)- Version is read directly from
galaxy.yml, sopublished_refis deterministic (no filename scraping) - Version pin for Ansible (
ansible_version); empty = latest - Writes a per-run summary table to
$GITHUB_STEP_SUMMARY - Exposes
published_ref,artifact_path, andcollection_versionoutputs
- Runner OS:
ubuntu-latest(also works on other OSes, but the rest of the Galaxy tooling is most commonly tested there). - Caller must run
actions/checkoutbefore this action. - Python 3.10+ is recommended (default
3.12). - Secret:
GALAXY_API_KEY(or any secret name you pass toapi_key). Required unlessdry_run: true.
name: Publish to Ansible Galaxy
on:
push:
tags: ["v*"]
workflow_dispatch:
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: somaz94/ansible-galaxy-publish-action@v1
with:
type: collection
api_key: ${{ secrets.GALAXY_API_KEY }}
namespace: somaz94
name: ansible_k8s_iac_toolname: Publish to Ansible Galaxy
on:
push:
tags: ["v*"]
workflow_dispatch:
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: somaz94/ansible-galaxy-publish-action@v1
with:
type: role
api_key: ${{ secrets.GALAXY_API_KEY }}
namespace: somaz94
name: ansible_kubectl_krew- uses: actions/checkout@v6
- uses: somaz94/ansible-galaxy-publish-action@v1
with:
type: collection
dry_run: true
namespace: somaz94
name: ansible_k8s_iac_toolThe build step still runs (so broken galaxy.yml / missing files fail CI), but no publish call is made. The built tarball is uploaded as a workflow artifact named collection-<namespace>-<name>-<version> so you can download and inspect it. The published_ref output is prefixed with dry-run: so downstream steps can branch on it.
- uses: somaz94/ansible-galaxy-publish-action@v1
with:
type: collection
api_key: ${{ secrets.GALAXY_API_KEY }}
ansible_version: '9.5.1'
namespace: somaz94
name: ansible_k8s_iac_tool- uses: somaz94/ansible-galaxy-publish-action@v1
with:
type: collection
api_key: ${{ secrets.GALAXY_API_KEY }}
working_directory: collections/somaz94/my_collection
namespace: somaz94
name: my_collection- id: galaxy
uses: somaz94/ansible-galaxy-publish-action@v1
with:
type: collection
api_key: ${{ secrets.GALAXY_API_KEY }}
namespace: somaz94
name: ansible_k8s_iac_tool
- name: Report
if: always()
run: |
echo "Published: ${{ steps.galaxy.outputs.published_ref }}"
echo "Version: ${{ steps.galaxy.outputs.collection_version }}"
echo "Artifact: ${{ steps.galaxy.outputs.artifact_path }}"| Input | Description | Required | Default |
|---|---|---|---|
type |
Publish target type: collection or role. |
Yes | — |
api_key |
Ansible Galaxy API key. Required unless dry_run: true. |
Conditional | '' |
namespace |
Galaxy namespace (e.g., somaz94). Used for both modes; in collection mode it must match galaxy.yml. |
Yes | — |
name |
Collection or role name under namespace (e.g., ansible_k8s_iac_tool or ansible_kubectl_krew). In collection mode it must match galaxy.yml. |
Yes | — |
working_directory |
Directory containing galaxy.yml (collection) or meta/main.yml (role). |
No | . |
python_version |
Python version for actions/setup-python. |
No | 3.12 |
ansible_version |
pip pin for Ansible (e.g., 9.5.1). Empty = latest. |
No | '' |
dry_run |
true or false (lowercase; any other value fails validation). When true, build the collection (if applicable), upload it as an artifact, and skip publish/import. |
No | false |
| Output | Description |
|---|---|
published_ref |
Published reference, e.g., collection/[email protected] or role/somaz94.ansible_kubectl_krew. Prefixed with dry-run: when dry_run is true. |
artifact_path |
Absolute path to the built collection tarball on the runner (collection mode only; empty for role mode). |
collection_version |
Version string read from galaxy.yml (collection mode only; empty for role mode). |
In collection + dry_run: true mode, the tarball is also uploaded as a workflow artifact named collection-<namespace>-<name>-<version> with a 7-day retention.
The action itself needs no special permissions beyond what actions/checkout and actions/setup-python require. A typical caller:
permissions:
contents: readThe Galaxy API key is supplied via the api_key input (typically ${{ secrets.GALAXY_API_KEY }}).
- Validate inputs —
typemust becollectionorrole;namespaceandnameare required;dry_runmust be exactlytrueorfalse(lowercase — the artifact-upload condition compares case-insensitively while bash does not, so a value likeTruewould split the mode);api_keyis required unlessdry_run: true. actions/setup-python— installs the requested Python version.- pip install — installs
ansible(oransible==<version>ifansible_versionis set); PyYAML comes as a transitive dependency. - Collection mode:
- Read
namespace,nameandversionfromgalaxy.ymlviayaml.safe_load→ emitcollection_versionoutput. Fails ifgalaxy.ymlcannot be parsed, has noversion, or itsnamespace/namediffer from the inputs (the build names the tarball fromgalaxy.yml, so a mismatch could pick up a stale tarball) ansible-galaxy collection build --forceinworking_directory- Locate the tarball
<namespace>-<name>-<version>.tar.gz→ expose viaartifact_path - When
dry_runisfalse, runansible-galaxy collection publish <tarball> --api-key=<key>; whentrue, skip and upload the tarball as a workflow artifact
- Read
- Role mode:
- When
dry_runisfalse, runansible-galaxy role import --api-key <key> <namespace> <name>
- When
- Summary & outputs — a markdown table is appended to
$GITHUB_STEP_SUMMARY(mode, namespace, name, version, ref, artifact). In dry-run mode the summary heading carriesdry-run; only thepublished_refoutput gets thedry-run:prefix.
This project is licensed under the MIT License — see the LICENSE file for details.