Skip to content

Standardise Ansible collections release process

Status

Proposed: defines a single, evidence-backed release process for all HybridOps Ansible collections (hybridops.app, hybridops.common, hybridops.helper, hybridops.network). Acceptance is contingent on the first end-to-end Galaxy release completed using this process.

1. Context

HybridOps maintains four Ansible collections:

  • hybridops.app: platform and application roles.
  • hybridops.common: shared plugins and cross-cutting utility roles.
  • hybridops.helper: evidence and NetBox helper roles.
  • hybridops.network: network automation roles.

These collections are:

  • Developed in a shared collections harness workspace.
  • Consumed by hybridops-core through pinned Galaxy requirements.
  • Intended to be published to Ansible Galaxy under the hybridops namespace.

Without a standard release process, the risks are:

  • Inconsistent test coverage between collections and roles.
  • Divergent or incomplete Galaxy metadata.
  • Weak traceability between ADRs, documentation, CI runs, and published release records.
  • Unclear expectations for maintainers and contributors when cutting a release.

The release process must therefore be:

  • Repeatable and automatable.
  • Aligned with the platform’s runtime-record model.
  • Simple enough to explain to reviewers, technical leaders, and clients.

2. Decision

HybridOps will use a single release process for all Ansible collections. This process is documented in:

  • This ADR (ADR-0606).
  • The internal MAINTAINERS.md file in the collections harness repository.
  • The public Ansible roles and collections index page: Ansible roles and collections reference.
  • A dedicated runbook and HOWTO (referenced in the header links; created as part of adopting this ADR).

The decision has five pillars.

2.1 Shared workspace and layout

  • All collections live in a shared workspace harness repository.

  • Layout is standardised:

  • collections/dev/workspace/ansible-collection-app/...

  • collections/dev/workspace/ansible-collection-common/...
  • collections/dev/workspace/ansible-collection-helper/...
  • collections/dev/workspace/ansible-collection-network/...

This keeps directory structure predictable for both humans and automation.

2.2 Galaxy metadata

  • Each collection maintains its own galaxy.yml at the collection root.

  • Namespaces and names are fixed:

  • namespace: hybridops

  • name: app | common | helper | network

  • Supported Ansible and Python versions in galaxy.yml are aligned with:

  • The shared harness toolchain used for collection CI and release checks.

  • The versions used in CI and role testing.

2.3 Testing gates

  • Each public role provides role-local tests under roles/<role>/tests/:

  • At minimum: tests/smoke.yml.

  • When needed: a local inventory or tests/hyops.role-test.yml.

  • Roles that depend on richer environments (for example jenkins_controller) may also provide Molecule scenarios under roles/<role>/molecule/.

  • Role smoke tests are executed through hyops test role.

  • The harness repository keeps a small Makefile wrapper for convenience:

  • make test ROLE=<role>: role-local smoke through hyops test role --local-inventory.

  • make test.state ROLE=<role> TEST_STATE_REF=... TEST_VM_GROUP=...: state-backed smoke through hyops test role --inventory-state-ref ....
  • make test.full ...: optional compatibility path that keeps the older connectivity gate plus a state-backed smoke test.

2.4 Evidence and documentation

  • CI pipelines that run collection tests write records under:

  • <runtime-root>/logs/test/role/...

  • The docs page Ansible roles and collections reference acts as the public index of:

  • Collections and their roles.

  • Test coverage (role-local, Molecule, integration).

  • Key usage examples and links back to ADRs.

  • MAINTAINERS.md captures the operational checklist (version bump, tests, evidence capture, Galaxy publish) in one place for maintainers.

2.5 Release steps and versioning

  • Tag scheme is consistent across collections:

  • v0.x.y-app

  • v0.x.y-common
  • v0.x.y-helper

  • v0.x.y-network

  • For each collection release:

  • Update galaxy.yml version and the collection’s changelog.

  • Run the agreed test matrix:

    • Role-local tests/smoke.yml (for affected roles).
    • Molecule scenarios (where defined).
    • Platform integration via make test ROLE=… or make test.full ROLE=….

  • Capture run records and CI references under:

    • ../evidence/ci/collections-release/ where a release record is still maintained
    • <runtime-root>/logs/test/role/... for hyops test role runs

  • Build and publish to Galaxy with:

    • ansible-galaxy collection build
    • ansible-galaxy collection publish

3. Rationale

The chosen approach:

  • Reduces cognitive load

  • Contributors learn one release process, regardless of whether they work on app, common, helper, or network.

  • Aligns collections with the HybridOps execution story

  • Role smoke tests use the same runtime root, state resolution, and run-record model as the rest of HybridOps.Core.

  • Strengthens traceability

  • Every published Galaxy record can be traced back to:

    • An ADR (this document).
    • A maintainer checklist (MAINTAINERS.md).
    • Concrete run records under <runtime-root>/logs/test/role/....
    • Entries in the public roles and collections index.

  • Supports commercial and teaching use-cases

  • It is straightforward to show how roles are tested and released when teaching, interviewing, or working with clients.

Trade-offs:

  • More ceremony per release (tests, evidence capture, docs updates).
  • Collections still rely on a shared workspace harness repository, and some integration tests still depend on a prepared runtime state source.

These trade-offs are acceptable given HybridOps’s emphasis on repeatability, transparency, and evidence-driven automation.

4. Consequences

4.1 Positive

  • Predictable releases

  • All collections follow the same steps from change to Galaxy record.

  • Clear onboarding

  • New contributors and learners can follow MAINTAINERS.md and the role index to understand expectations.

  • Coherent namespace

  • The hybridops namespace on Galaxy clearly mirrors platform domains and documentation.

  • Reuse of shared runtime infrastructure

  • State-backed role smoke tests can reuse provisioned hosts from HybridOps runtime state instead of rebuilding separate bespoke harnesses per collection.

4.2 Negative / risks

  • Dependency on prepared runtime state

  • Full state-backed integration tests still require a prepared runtime state source; otherwise only role-local and Molecule tests are available.

  • Maintenance overhead

  • ADRs, the role index, MAINTAINERS.md, and galaxy.yml files must be kept aligned as roles evolve.

  • CI cost

  • Integration runs that provision or refresh generic VMs are more resource-intensive than Molecule-only tests.

Mitigations:

  • Support lighter local workflows (role-local tests/ and Molecule) where platform access is not available.
  • Automate parts of the checklist with CI jobs and Make targets.
  • Periodically review collections to retire or refactor low-value roles.

5. Alternatives considered

  1. Separate repository per collection

  2. Each collection would have its own repository, CI, and release process.

  3. Rejected due to operational overhead and the desire for a single teaching workspace and shared harness.

  4. No Galaxy publication

  5. Collections would remain internal to the main platform codebase.

  6. Rejected because public Galaxy records are valuable for documentation, Academy content, formal technical review, and third-party reuse.

  7. Molecule-only testing

  8. Validation would rely solely on Molecule scenarios.

  9. Rejected because HybridOps emphasises end-to-end flows against realistic VMs and networks, not just container-based tests.

6. Implementation notes

Collections harness workspace:

  • Root Makefile:

  • test, test.syntax: run role-local smoke checks through hyops test role.

  • test.state, test.state.syntax: run state-backed smoke checks through hyops test role.

  • test.connectivity, test.full: optional compatibility path for the older external connectivity gate.

  • Each collection:

  • galaxy.yml with namespace, name, version, and dependencies.

  • requirements.txt with aligned Ansible/Molecule/lint tool versions.
  • README.md describing scope, roles, and how tests are structured (role-local, Molecule, integration).

Prepared runtime compatibility path:

  • Compatibility inventory:

  • deployment/inventories/core/cicd-test.ini.

  • Compatibility connectivity playbook:

  • deployment/ci/playbooks/cicd_connectivity_gate.yml.

  • HybridOps-native run record tree:

  • <runtime-root>/logs/test/role/....

Future CI/CD integration:

  • Jenkins (or equivalent) pipelines that:

  • Checkout the collections harness repository and any required prepared runtime inputs.

  • Run make test.syntax, make test.state.syntax, and selected real smoke runs for release-surface roles.
  • Archive role smoke run records and surface links via the docs site.

7. Operational impact and validation

Operational impact:

  • Maintainers follow MAINTAINERS.md for each collection release.

  • New or updated roles only ship once they have:

  • Role-local tests.

  • Updated index entries.
  • A passing run through the agreed test matrix.

Validation:

  • The release runbook and HOWTO (referenced in the header) are exercised each time a new tag is created.
  • CI dashboards show the last successful integration run per key role (for example jenkins_controller, linux_rke2_install).

  • Evidence directories contain:

  • Logs and records from Molecule and integration runs.

  • Galaxy build records (*.tar.gz) and copies of the galaxy.yml used.

8. References

Runbooks