Skip to content

Releasing

Releases are cut from main, are tagged vX.Y.Z, and publish to Ansible Galaxy automatically. The pipeline hard-gates the tag against galaxy.yml, so the only supported way to release is the script - it keeps the two in lockstep by construction.

The versioning contract

  • Semantic versioning. Breaking changes only in major releases; new modules and options are minor releases; fixes are patches.
  • Removals are tombstoned. A removed module name keeps failing with an actionable message (see meta/runtime.yml) pointing at its replacement and the migration guide - never with a bare "module not found".
  • The changelog is compiled, not written. antsibull-changelog renders fragments into CHANGELOG.rst at release time.

Cutting a release

$ git checkout main && git pull
$ make lint sanity units docs-check           # everything green before you tag
$ scripts/release.sh 2.1.0
galaxy.yml -> 2.1.0
...
Release commit and tag created. Publish with:
  git push origin HEAD v2.1.0
$ git push origin HEAD v2.1.0

What scripts/release.sh X.Y.Z does:

  1. Bumps version: in galaxy.yml.
  2. Runs antsibull-changelog release --version X.Y.Z - consumes changelogs/fragments/* and renders CHANGELOG.rst (and CHANGELOG.md for this site's release notes).
  3. Commits galaxy.yml + changelog and creates the vX.Y.Z tag.

Pushing the tag triggers the publish job: it re-verifies tag == galaxy.yml version, builds the artifact, and publishes it to Galaxy with the GALAXY_API_KEY CI/CD variable. The merge to main also redeploys the documentation site.

Maintainer prerequisites

  • Rights to push tags to the repository.
  • The GALAXY_API_KEY CI/CD variable set to a Galaxy token for the netautomate namespace (Settings → CI/CD → Variables, masked).

If the publish job fails

  • galaxy.yml version (X) does not match tag (vY) - the tag was created by hand. Delete the tag, run scripts/release.sh, push again.
  • Galaxy rejects the upload - version already exists on Galaxy (versions are immutable there): bump to the next patch and release again; there is no re-publishing a version.