Skip to content

Runbook – Ansible Collections Release

  • Purpose: Release a HybridOps Ansible collection to Galaxy and update hybridops-core to consume the published version.
  • Trigger: Planned collection release after role validation and packaging checks.
  • Impact: A bad release breaks hyops setup ansible and downstream Ansible execution.
  • Severity: P2.

Scope

This runbook covers the collections currently on the clean release path:

  • hybridops.common
  • hybridops.app
  • hybridops.helper

hybridops.network can be built and packaged, but it is not part of the current hybridops-core shipping path and should be released separately when its module-backed validation is ready.

Preconditions

  • The target collection repo has:
  • updated galaxy.yml
  • updated meta/runtime.yml
  • clean package surface
  • passing hyops test role smoke checks or an equivalent integration-backed validation path
  • The repo GitHub Actions secrets include ANSIBLE_GALAXY_API_KEY
  • The publish workflow is present under .github/workflows/release.yml
  • hybridops-core is ready to pin the target version in tools/setup/requirements/ansible.galaxy.yml

Release model

The current release flow is:

  1. validate and build in the collection repo
  2. push a version tag that matches galaxy.yml
  3. let GitHub Actions publish the tarball to Galaxy
  4. update hybridops-core to consume the published version
  5. run hyops setup ansible
  6. verify runtime-installed Galaxy collections take precedence over vendored fallback

Publication is tag-driven, not commit-driven.

Steps

  1. Choose the collection and version

  2. Example:

     export COLLECTION_REPO=/path/to/ansible-collection-common
 export VERSION=0.1.1

  3. Confirm galaxy.yml matches the intended version:

     python3 - <<'PY'
 import yaml
 from pathlib import Path
 p = Path("galaxy.yml")
 print(yaml.safe_load(p.read_text())["version"])
 PY

  4. Run local release checks

  5. Build:

     ansible-galaxy collection build --force

  6. Run the relevant role smoke checks through hyops test role for the roles actually being shipped.

  7. Prefer syntax-check first, then a real role-local or state-backed smoke execution.
  8. Record the build and validation logs under the normal runtime run-record path.

Example:

   hyops test role hybridops.common.postgresql_service \
     --env dev \
     --workspace-root /path/to/hybridops-collections-src/collections/dev/workspace \
     --local-inventory \
     --syntax-check
  1. Confirm the workflow shape
  2. CI must run on push main and PRs.

  3. Publish must run on version tags:

     on:
   push:
     tags: ["v*"]

  4. The release workflow must verify tag/version match before publish.

  5. Commit the release

  6. Commit the version bump, changelog, and any release-surface fixes:

     git add .
 git commit -m "release: hybridops.<name> v${VERSION}"
 git push origin main

  7. Create and push the release tag

  8. The tag must match galaxy.yml exactly:

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

  9. This triggers the collection publish workflow.

  10. Verify Galaxy publish

  11. Check GitHub Actions for the publish run.
  12. Confirm the collection appears on Galaxy at the expected version.

  13. Validate install from a clean path:

     ansible-galaxy collection install hybridops.<name>:==${VERSION} --force

  14. Update hybridops-core consumption

  15. Pin the released version in hybridops-core/tools/setup/requirements/ansible.galaxy.yml.
  16. Treat those shared hybridops.* entries as explicit Galaxy pins, not floating versions.

  17. Run:

     hyops setup ansible

  18. Confirm the runtime installs into:

    • <runtime_root>/state/ansible/galaxy_collections

  19. Confirm those runtime-installed collections are preferred over vendored fallback.

  20. Verify one shipped path

  21. Run one representative module or blueprint that uses the published collection.
  22. Example paths:
    • platform/linux/eve-ng
    • platform/network/dns-routing
    • platform/onprem/postgresql-ha-backup

Verification

  • ansible-galaxy collection build --force succeeds locally
  • hyops test role ... succeeds for the release-surface roles being changed
  • The publish workflow succeeds on the pushed version tag
  • Galaxy shows the expected version
  • hyops setup ansible installs the pinned version into runtime state
  • A representative hybridops-core module path succeeds against the published collection

Rollback

If the release is bad:

  1. revert the version bump in the collection repo
  2. publish a corrected version rather than mutating the existing Galaxy record
  3. revert the pin in hybridops-core
  4. rerun hyops setup ansible

Do not rely on vendored fallback as the rollback plan for a shipped release.

References

  • docs/adr/ADR-0606-ansible-collections-release-process.md
  • hybridops-core/tools/setup/README.md
  • hybridops-core/tools/setup/requirements/ansible.galaxy.yml