| name | release |
| description | Guides the release of an Ansible collection following the upstream process (without release branches). Automatically determines the next version from changelog fragments. Outputs step-by-step instructions with commands for changelog generation, release PR, tagging, Galaxy publication, version bump, and GitHub release. Use when asked to release, publish, or tag a new collection version. |
Skill: release
Purpose
Guide the release of an Ansible collection. This skill is collection-generic — it derives namespace, name, and current version from galaxy.yml, and automatically determines the next version from changelog fragment categories.
When to Invoke
TRIGGER when:
- A user asks to release, publish, or tag a new collection version
- A user asks about the release process or release checklist
DO NOT TRIGGER when:
- Reviewing a PR (use
pr-review skill instead)
- Running tests (use
run-tests skill instead)
- General changelog or versioning questions unrelated to performing a release
Inputs
version (optional): the target release version, e.g. 2.1.0. If not provided, the version is automatically determined from changelog fragments (see Step 1).
Prerequisites
antsibull-changelog installed (pip install antsibull-changelog)gh CLI installed and authenticated- Push access to the upstream remote
Human Confirmation Gates
Do not proceed past a confirmation gate without explicit human approval. Present the relevant information and wait for the human to confirm before continuing to the next step. Gates are marked with CONFIRM below.
Release Steps
Step 1 — Read collection context and determine version
Extract collection identity from galaxy.yml:
grep -E '^(namespace|name|version):' galaxy.yml
Use the extracted values as NAMESPACE, COLLECTION, and CURRENT_VERSION in all subsequent steps.
Determine next version
If the user did not provide a target version, determine it automatically:
- Scan all YAML files in
changelogs/fragments/ and collect the top-level keys (category names) from each file.
- Determine the version bump using the highest-severity category found:
| Bump | Fragment categories |
|---|
| Major | breaking_changes, removed_features, major_changes |
| Minor | minor_changes, deprecated_features |
| Patch | bugfixes, security_fixes, known_issues, trivial |
- Apply the bump to
CURRENT_VERSION (e.g. 2.0.0 + minor → 2.1.0). When bumping major, reset minor and patch to 0. When bumping minor, reset patch to 0.
Use the resulting version as VERSION.
CONFIRM: Present the extracted NAMESPACE, COLLECTION, CURRENT_VERSION, the detected fragment categories, the determined bump type, and the resulting VERSION to the human. Ask them to confirm these values are correct before proceeding. The human may override the version at this point.
Step 2 — Pre-flight checks
git status
git checkout main
git pull --rebase upstream main
Verify before continuing:
- Working tree is clean (no uncommitted changes)
- Changelog fragments exist:
ls changelogs/fragments/
Step 3 — Update galaxy.yml version
If CURRENT_VERSION in galaxy.yml does not match VERSION, update it:
sed -i "s/^version: .*/version: VERSION/" galaxy.yml
Step 4 — Create release branch
git checkout -b release_VERSION
Step 5 — Generate changelog
Determine the release type from VERSION and suggest a release summary using this template:
- Major (
X.0.0): This is a major release of the ``NAMESPACE.COLLECTION`` collection.
- Minor (
X.Y.0): This is a minor release of the ``NAMESPACE.COLLECTION`` collection.
- Patch (
X.Y.Z): This is a patch release of the ``NAMESPACE.COLLECTION`` collection.
Followed by:
This changelog contains all changes to the modules and plugins in this collection that have been made after the previous release.
CONFIRM: Present the suggested release summary and the list of changelog fragments that will be included. Ask the human to approve or edit the text before writing the fragment.
Create the release summary fragment:
cat > changelogs/fragments/VERSION.yml << 'EOF'
release_summary: |-
This is a <major/minor/patch> release of the ``NAMESPACE.COLLECTION`` collection.
This changelog contains all changes to the modules and plugins in this collection
that have been made after the previous release.
EOF
Generate the changelog:
antsibull-changelog release --reload-plugins
CONFIRM: Show the human the generated CHANGELOG.rst diff and ask them to confirm the content is correct before continuing.
Step 6 — Commit and push release branch
git add -A
git commit -m "Release VERSION"
git push origin release_VERSION
Step 7 — Create pull request
gh pr create --title "Release VERSION" --body "Release VERSION of NAMESPACE.COLLECTION."
CONFIRM: Wait for the human to confirm that CI has passed and the PR has been reviewed and merged before continuing.
Step 8 — Update local main
After the PR is merged:
git checkout main
git pull --rebase upstream main
Step 9 — Tag and push
CONFIRM: Ask the human to confirm before creating and pushing the tag. This action is irreversible.
git tag -a VERSION -m "NAMESPACE.COLLECTION: VERSION"
git push upstream VERSION
Step 10 — Create GitHub release
gh release create VERSION --title "VERSION" --notes "See [CHANGELOG.rst](https://github.com/NAMESPACE/COLLECTION/blob/main/CHANGELOG.rst) for details."
Step 11 — Bullhorn release announcement
Generate and present the following announcement text for the user to post in the Bullhorn newsletter after the user ensures the release has appeared on Ansible Galaxy:
The [NAMESPACE.COLLECTION](https://galaxy.ansible.com/ui/repo/published/NAMESPACE/COLLECTION/) collection version [VERSION](https://github.com/ansible-collections/NAMESPACE.COLLECTION/blob/main/CHANGELOG.rst#vVERSION) has been released!
Replace NAMESPACE, COLLECTION, and VERSION with the actual values. In the anchor fragment (#vVERSION), replace dots with hyphens (e.g. #v2-1-0 for version 2.1.0).
Output Format
Present each step as a numbered section containing:
- What the step does (one line)
- The exact command(s) to run (with placeholders replaced by actual values)
- What to verify before proceeding to the next step
