How SKAO release management works#

Release management makes a software version traceable from the change that introduced it to the artefacts published for it. Pipeline Machinery provides a consistent mechanism, but each product remains responsible for deciding when a version is ready and for validating its published artefacts.

The release lifecycle#

Teams develop and validate changes through merge requests. When the changes are ready to publish, the release owner creates a REL Jira ticket, increments the project version, and creates a Git tag. The pushed tag starts the release pipeline.

Release lifecycle from REL ticket, version bump, review, Git tag and tag pipeline to published releases and artefacts, followed by verification. — The release workflow keeps the delivery record, source version, published artefacts, and verification evidence connected.#

Pipeline Machinery reads the version from .release and updates supported artefact metadata. The tag pipeline then builds and publishes configured artefacts, generates release notes, and creates a GitLab Release. The release automation can update the REL ticket with links to the release notes.

The version bump and the tag are deliberately separate steps. The bump records the intended version in the source tree. The pushed tag is the immutable event that starts publication. Reviewing the version changes before creating the tag prevents a mismatch between source metadata and published artefacts.

Why REL tickets matter#

A REL ticket records the reason for a release and provides a link between delivery coordination, the version-bump commit, and the published GitLab Release. Include the ticket key in the release commit when the release target requests it. The generated release notes can then link the GitLab Release back to the ticket.

Release candidates#

Release candidates let teams validate a version before publishing the final release. They use the same version-management workflow, but keep a release-candidate suffix until the candidate is promoted.

Changelogs and release notes#

The changelog is both a communication tool and an audit trail. Pipeline Machinery uses git-chglog to create the generated part of CHANGELOG.md and preserves author notes placed under an Author Notes heading for a release. This lets teams add information that commit messages cannot express while retaining generated release history.

Published artefacts and traceability#

The release is more than a Git tag. Publishing targets attach artefact links to the GitLab Release so readers can find the released outputs. Pipeline Machinery also adds build and provenance metadata: OCI images receive labels, while other artefact types receive a MANIFEST.skao.int file. This metadata records how and where an artefact was built, supporting traceability across the software supply chain.