Create a software release with Pipeline Machinery

This tutorial creates a patch release using the release targets provided by ska-cicd-makefile. Use the same workflow for a minor or major release after choosing the appropriate version increment.

Prepare the project

Your project must include Pipeline Machinery and the release makefile:

-include .make/release.mk

Your .gitlab-ci.yml must also include the release template. See Configure automated release jobs for the required configuration.

Work from the branch that the project uses for releases. Ensure the release changes have been reviewed and validated, and that you have permission to create and push the tag. A pushed tag can publish artefacts and create a GitLab Release.

Create a REL ticket

Create a ticket in the Release Management Jira project. Follow Create a release management ticket for the required Jira task. Use its key, for example REL-123, when the release target asks for a Jira ticket ID. The release pipeline uses this key to add release-note links to the ticket.

Check the working tree

Check that the release starts from a clean working tree:

make check-status

This target rejects outstanding tracked changes that are unrelated to the generated release files. Commit, stash, or discard unrelated work before you bump the version. The version bump can then update its expected files without mixing the release with unrelated changes.

Bump the version

Check the current version:

make show-version

Choose the required semantic-version increment and run one target. A patch release changes 1.2.1 to 1.2.2:

Choose a version increment

Release type	Use it when	Example	Target
Patch	You deliver backward-compatible bug fixes without new features.	1.2.1 to 1.2.2	make bump-patch-release
Minor	You deliver backward-compatible functionality.	1.2.1 to 1.3.0	make bump-minor-release
Major	You introduce incompatible API or behaviour changes.	1.2.1 to 2.0.0	make bump-major-release
Release candidate	You need to validate a planned release before its final publication.	1.3.0 to 1.3.0-rc.1	make bump-rc

Confirm the version type with the product owner or release coordination process when the compatibility impact is unclear.

make bump-patch-release

Use make bump-minor-release to change 1.2.1 to 1.3.0 or make bump-major-release to change it to 2.0.0. Each bump target calls make set-release. This updates .release and, where present, Python package metadata, Helm chart versions and dependencies, Conan package metadata, JavaScript package metadata, and docs/src/conf.py.

Review the resulting changes before continuing. Update any version assertions, human-written changelog material, or other product metadata that the automatic targets do not manage.

Before creating the tag, you can use make check-release to verify an existing release tag and that its source matches the working directory. This is most useful when checking an already-published version; a new version has no tag until you create one.

Create and push the tag

Create the release commit and Git tag:

make create-git-tag

In the normal workflow, commit the release changes before running this target. It then creates the calculated tag without prompting. If tracked changes remain and AUTO_RELEASE is false, the target asks you to confirm the commit and enter the REL ticket key before creating the tag. Then push the release commit and tag:

make push-git-tag

The tag pipeline publishes configured artefacts, creates the GitLab Release, and updates the REL ticket when the release jobs are enabled.

Verify the published release

Open the tag pipeline and confirm that it ran for the expected version tag. Check that its configured publication jobs completed successfully. Job names and stages differ between projects.

A successful tag pipeline runs the project-specific build and publication jobs for the release tag.

Open the generated GitLab Release and confirm that it has the expected version, generated release notes, and published assets or artefact links. Check the REL ticket for the release-note links when your project enables that integration.

A GitLab Release provides a single view of the version, release notes, downloadable assets, and published artefacts.

Create a release candidate

First bump the intended release version, then create the release candidate:

make bump-minor-release
make bump-rc

Repeat make bump-rc to increment the candidate number. The common release format is X.Y.Z-rc.N; Python package metadata uses the PEP 440-compatible form X.Y.ZrcN. After validation, promote the candidate:

make rc-to-release

Create and push the resulting Git tag as described above.

Recover from a release mistake

If you have only changed release files locally, restore the affected files before creating a tag. Do not use a broad restore command when you have unrelated uncommitted work.

git restore .release pyproject.toml

Adjust the file list for your project, then repeat the required bump target.

If the incorrect version has been pushed but no tag pipeline has run, correct the version through the normal review and merge process before tagging. If a tag pipeline has already published the release, do not reuse the version or retag it. Mark the release as incorrect through the applicable product process and create a new release with the correct version.