Runbook – Ansible Collections Release¶

Purpose: Release a HybridOps Ansible collection (app/common/helper/network) to Galaxy with the agreed test and evidence trail.
Owner: Platform / CICD
Trigger: Planned release, dependency update, or after merging feature/bugfix branches that need a Galaxy publish.
Impact: Downstream consumers pull the new collection version; broken releases impact platform CI and customer automation.
Severity: P2 (high — blocks platform pipelines if incorrect).
Pre-reqs: Access to ansible-galaxy-hybridops and Galaxy hybridops namespace, ansible-galaxy logged in, hybridops-platform checkout for integration tests, working make, Python toolchain, and ability to write evidence under ../evidence/ci/collections-release/ and output/artifacts/ci/collections/.
Rollback strategy: Revert version/changelog, republish the previous tarball to Galaxy, and pin platform collections/requirements.yml to the prior tag if needed.

Context¶

This runbook codifies the release flow defined in ADR-0606. All collections live in the shared ansible-galaxy-hybridops workspace. Each release must:

Bump galaxy.yml version and changelog for the target collection.
Pass role-local tests, Molecule scenarios (if present), and platform integration gates.
Produce evidence under ../evidence/ci/collections-release/ and hybridops-platform/output/artifacts/ci/collections/.
Publish to Galaxy under the hybridops namespace with tags v0.x.y-<collection>.

Preconditions and safety checks¶

Confirm the correct branch and clean working tree in ansible-galaxy-hybridops:

git status

Validate Galaxy auth is available (expects ~/.ansible/galaxy_token or equivalent):

ansible-galaxy collection list | grep hybridops || true

Ensure the shared virtualenv exists (from ansible-galaxy-hybridops root):

make venv.refresh

Identify the collection and target version (for commands below, set variables):

export COLLECTION=app            # app | common | helper | network
export VERSION=0.4.0             # new version to release

Steps¶

1) Update metadata and changelog - Action: Bump the version in ansible-collection-${COLLECTION}/galaxy.yml and update the collection changelog for the release notes. - Command:

yq -i ".version = \"${VERSION}\"" ansible-collection-${COLLECTION}/galaxy.yml
# Edit changelog as needed

- Expected result: galaxy.yml version matches ${VERSION}; changelog captures highlights and ADR reference. - Evidence: Commit diff or saved snippet in ../evidence/ci/collections-release/${COLLECTION}_${VERSION}_changelog.txt.

2) Run connectivity gate - Action: Validate base connectivity to CI test hosts. - Command:

make test.connectivity

- Expected result: Connectivity play succeeds; no unreachable hosts. - Evidence: Save console output to ../evidence/ci/collections-release/${COLLECTION}_${VERSION}_connectivity.log.

3) Run role smoke tests (per affected role) - Action: Execute role-local smoke tests for changed roles. - Command:

make test ROLE=<role_name>
# Use make test.full ROLE=<role_name> if you need connectivity + smoke in one call

- Expected result: Smoke tests pass for each impacted role. - Evidence: Logs under output/artifacts/ci/collections/<role>/ in hybridops-platform plus copied summary in ../evidence/ci/collections-release/${COLLECTION}_${VERSION}_smoke_<role>.log.

4) Run Molecule scenarios (if defined) - Action: Execute Molecule for roles that have scenarios. - Command (example):

cd ansible-collection-${COLLECTION}
molecule test -s <scenario>   # skip if role has no Molecule
cd -

- Expected result: Molecule tests pass; instances cleaned up. - Evidence: Molecule logs saved alongside smoke test evidence.

5) Build the collection - Action: Create the Galaxy artifact tarball. - Command:

cd ansible-collection-${COLLECTION}
ansible-galaxy collection build
cd -

- Expected result: ansible-collection-${COLLECTION}/build/hybridops-${COLLECTION}-${VERSION}.tar.gz created. - Evidence: SHA256 checksum saved to ../evidence/ci/collections-release/${COLLECTION}_${VERSION}_sha256.txt:

shasum -a 256 ansible-collection-${COLLECTION}/build/hybridops-${COLLECTION}-${VERSION}.tar.gz | tee ../evidence/ci/collections-release/${COLLECTION}_${VERSION}_sha256.txt

6) Publish to Galaxy - Action: Upload the built tarball. - Command:

ansible-galaxy collection publish ansible-collection-${COLLECTION}/build/hybridops-${COLLECTION}-${VERSION}.tar.gz

- Expected result: Galaxy returns success with the new version visible under hybridops.${COLLECTION}. - Evidence: Capture publish output in ../evidence/ci/collections-release/${COLLECTION}_${VERSION}_publish.log.

7) Tag and push - Action: Tag the repo with the collection-specific tag and push. - Command:

git tag "v${VERSION}-${COLLECTION}"
git push origin "v${VERSION}-${COLLECTION}"

- Expected result: Tag exists remotely; CI can consume it. - Evidence: Tag reference noted in the release evidence folder.

8) Update platform consumers - Action: Update collections/requirements.yml in hybridops-platform (or downstream repos) to the new version and run a quick install check. - Command (run inside hybridops-platform):

ansible-galaxy collection install -r collections/requirements.yml --force

- Expected result: New collection version installs cleanly. - Evidence: Install log saved to output/artifacts/ci/collections/${COLLECTION}/install_${VERSION}.log.

Verification¶

Galaxy shows the new version for hybridops.${COLLECTION} with the correct metadata.
ansible-galaxy collection install hybridops.${COLLECTION}:${VERSION} succeeds on a clean environment.
All smoke/Molecule/integration logs stored under ../evidence/ci/collections-release/ and hybridops-platform/output/artifacts/ci/collections/ with timestamps.
Relevant ADRs/HOWTOs updated if release steps changed (ADR-0606, HOWTO for collections release).

Post-actions and clean-up¶

Close or update the release ticket/change record with links to evidence and Galaxy release page.
Remove temporary local build artefacts if not needed beyond evidence:

rm -f ansible-collection-${COLLECTION}/build/hybridops-${COLLECTION}-${VERSION}.tar.gz

Schedule follow-up testing in platform CI if the release included breaking changes.
Add notes to MAINTAINERS.md if the process changed or if new edge cases were discovered.

References¶

Maintainer: HybridOps.Studio
License: MIT-0 for code, CC-BY-4.0 for documentation