Runbook: Release a role

Releasing a role is the moment it stops being yours. After publication, other teams install it by version, pin it, and run it against hosts you do not know about. Every assumption you left implicit becomes their problem, and the version number is the only thing telling them how much to worry.

This runbook is deliberately conservative about two things: what counts as a breaking change, and never republishing a version that already exists.

When to use this runbook

• Cutting a release of an internal collection.
• Publishing a shared role that other repositories consume.
• Releasing a fix that consumers need to pick up deliberately.
• Promoting a role from one team’s repository into shared ownership.

Blast radius

Publishing itself changes nothing - no consumer picks up a new version until they change their pin. That is the design, and it is why pinning matters.

The blast radius is delayed and indirect: every consumer that upgrades, across every host they manage. You will not see it, which is exactly why the changelog and the version number carry the weight here.

Inputs

• The consumer list.
• The previous released version and its tag.
• The commit to be released.
• The test matrix definition and its last full result.

Step 1: Read the diff and classify it

git fetch --tags
git log --oneline 1.4.2..HEAD
git diff 1.4.2..HEAD -- roles/nginx_frontend/defaults roles/nginx_frontend/meta

The second command is the one that decides the version. defaults/ and meta/argument_specs.yml are the role’s public interface; changes elsewhere are implementation.

Classify every change in that diff:

Step 2: Decide the version

Derive it from the table, not from how big the work felt. A three-line change that renames a variable is a major release. A two-thousand-line refactor with an identical interface is a patch.

If the estate does not use semantic versioning, use whatever it does use - but the classification above still decides which slot moves, and consumers still need to be able to read the number and know whether to be careful.

Step 3: Write the changelog

## 2.0.0 - 2026-08-11

### Breaking changes
- nginx_frontend_workers renamed to nginx_frontend_worker_processes.
Rename the variable in your group_vars. No behaviour change.
- Default listen port changed from 80 to 8080. If you relied on the
default, set nginx_frontend_listen_port: 80 explicitly BEFORE
upgrading, or the next converge will move the listener.

### Added
- nginx_frontend_upstreams accepts a list of backend addresses.

### Fixed
- Config template no longer emits a duplicate server_name directive
when nginx_frontend_site contains a dot.

Every breaking entry needs the migration, in the entry, in the imperative. “Renamed X to Y” tells a reader what happened. “Rename the variable in your group_vars” tells them what to do, which is what they are reading it for at 9am on an upgrade day.

Step 4: Freeze

git checkout -b release/2.0.0
git log -1 --format='%H %ci %s'

Record that hash. Everything from here tests this commit. A fix merged to the main branch during the release does not go into this release; it goes into the next one.

The failure this prevents is the tag that points somewhere the test matrix never ran. It happens quietly: a merge lands while the matrix is running, the tag is cut from the branch head afterwards, and the released artefact contains code that was never tested.

Step 5: Full test matrix on the candidate

cd roles/nginx_frontend
molecule test --all 2>&1 | tee "release-2.0.0-matrix.log"
grep -E 'idempotence|verify|FAILED' "release-2.0.0-matrix.log" | tail -20

Every platform the role’s metadata claims to support gets a scenario. If a claimed platform has no scenario, you have two honest options: write the scenario, or remove the claim. Releasing with an untested platform in meta/main.yml is telling consumers you tested something you did not.

The idempotence step is not optional here. A role that converges twice with changes is a role that will produce a service restart on every run across every consumer’s estate.

Step 6: Build, then install what you built

cd /srv/automation/collections/example/infra
ansible-galaxy collection build --output-path /tmp/release
ls -l /tmp/release/

rm -rf /tmp/verify-collections
ansible-galaxy collection install \
/tmp/release/example-infra-2.0.0.tar.gz \
-p /tmp/verify-collections

ANSIBLE_COLLECTIONS_PATH=/tmp/verify-collections ansible-galaxy collection list

Step 7: Run a consumer playbook against the artefact

cd /tmp/consumer-test
ANSIBLE_COLLECTIONS_PATH=/tmp/verify-collections \
ansible-playbook consumer.yml --syntax-check

ANSIBLE_COLLECTIONS_PATH=/tmp/verify-collections \
ansible-playbook consumer.yml --limit staging-web01.example.com --check --diff

Use a real consumer playbook if you have one, referring to the role by its fully qualified name. That is the call path consumers use, and it is where a namespace or naming mistake surfaces.

Step 8: Tag and publish

git tag -a 2.0.0 -m 'Release 2.0.0 - see CHANGELOG.md'
git push origin 2.0.0

ansible-galaxy collection publish \
/tmp/release/example-infra-2.0.0.tar.gz \
--server internal_galaxy

Configure the server and its token in ansible.cfg under a [galaxy_server.internal_galaxy] section, or supply the token from an environment variable in CI. Do not paste a token on the command line - it lands in shell history and in the process table.

Step 9: Verify the published version installs

rm -rf /tmp/published-check
ansible-galaxy collection install 'example.infra:==2.0.0' \
-p /tmp/published-check -s internal_galaxy
ANSIBLE_COLLECTIONS_PATH=/tmp/published-check ansible-galaxy collection list

Then confirm the rollback path still works, because that is what consumers will reach for:

rm -rf /tmp/previous-check
ansible-galaxy collection install 'example.infra:==1.4.2' \
-p /tmp/previous-check -s internal_galaxy

A release that removed the previous version from the store is a release with no rollback, and consumers find that out at the worst time.

Step 10: Notify consumers

Send the version, the changelog, and - for a major release - the migration steps, directly to the consumer list. Do not rely on them noticing a tag.

Then stop. Updating a consumer’s pin is not part of this runbook. Each consumer upgrades on their own schedule, through their own change process, with their own canary. A release that arrives already applied to someone else’s estate is not a release, it is a change you made to their infrastructure.

Rollback

ansible-galaxy collection install 'example.infra:==1.4.2' \
-p ./collections --force
ansible-galaxy collection list | grep example.infra

--force is required. Without it ansible-galaxy sees a version already installed and leaves it alone, so the “downgrade” reports success and changes nothing - and the next play runs the broken version. Check the collection list output afterwards; do not trust the install message.

Common patterns

Escalation

Escalate when:

• The release contains a breaking change. Consumers need telling before, not after.
• A supported platform cannot be tested.
• The artefact store wants you to overwrite an existing version.
• A published version must be withdrawn.