Release workflow
The big picture: A release is three moves: audit everything since the last tag
(/pre-release), cut a release branch with the changelog assembled and versions bumped
(/release), then merge it and tag by hand. If the project ships packages or images, the
tag also triggers a publish stage.
Why it matters: Release day is when mistakes become public and permanent. A whole-release audit catches what per-branch reviews can’t see, and a scripted cut runs the same checks every time.
How it works:
/pre-release fullat feature freeze; fix the blockers; run it once more before tagging./releaseopens achore/release-X.Y.Zbranch and MR.- After it merges and its pipeline is green:
git tag, push the tag,glab release create.
Pre-release audit
Section titled “Pre-release audit”Before cutting a release, run a cross-cutting audit of the codebase:
/pre-release full # run all audits (security, perf, regression, docs)/pre-release security # security only/pre-release performance # performance onlyThis catches issues that day-to-day feature agents miss because they are domain-scoped. The pre-release audit applies a “what becomes a public commitment?” lens across the full codebase.
This is a one-time gate, not an iterative loop. Run once at feature freeze, triage findings, fix blockers, then run once more as a final check.
After a full audit with blocking or important findings, /pre-release names, for each
finding, the day-to-day gate that should have caught it during feature work, and proposes
a rule for the whole class of defect, not the one instance: it extends an existing rule
rather than adding a duplicate, cites the finding’s issue, and files a kaizen issue when
no gate fits. The rules you approve and decline are recorded on one write-back issue and land in
their own MR, and a later run skips a finding already written back. This write-back never
triggers a re-run of the audit (ships in 0.8).
Every audit type also checks for unresolved security::deferred issues, including ones
closed or unlabeled by someone who may not clear them — see
Deferred security follow-ups. scripts/release.sh
re-runs the same check immediately before a GA tag.
Cutting the release
Section titled “Cutting the release”/release [version]The /release command handles the full flow:
-
Determine version — reads
CHANGELOG.md [Unreleased]and suggests semver (patch for fixes only, minor for added features, major for breaking changes) -
Pre-flight — parallel checks: clean working tree, changelog entries exist, documentation covers all new features, and an inventory of the tag-only CI jobs that changed since the last tag (
scripts/check-tag-only-jobs.sh, wired intotooling-self-tests— see Harness gates). Those jobs run for the first time at the tag, so each is either probed beforehand or reported as unproven. -
Draft and approve the summary and notes together. Before running anything,
/releasedrafts a “Should you upgrade?” call (security fix, major bug fix, or routine release) and, only if some fragment breaks the upgrade, an “Upgrading from v{previous} or earlier? Read this first.” paragraph listing what breaks — both grounded in the changelog (this version’s fragments and, for a roll-up, the sections since the baseline), never guessed from the version bump./releasefirst classifies the target and states its baseline. A pre-release or a bug-fix-only patch is summarized as above. A stable feature release is rolled up instead: the summary covers everything since the baseline, the most recent earlier stable release that was not bug-fix-only (1.2.0after1.1.0and a bug-fix-only1.1.1has baseline1.1.0), reading every pre-release section in between. It keeps the headline features, the changes an upgrader must act on and the urgency line, and links to the full changelog sections./releaseasks you when it cannot tell whether a roll-up applies, when the baseline is ambiguous, or whether an item is headline or minutiae. For a roll-up, the summary file opens with a “What’s new since the baseline” section, and the upgrade paragraph keeps the previous stable tag in its heading but lists every breaking change since the baseline./releaseshows you both that draft and the rendered changelog fragments in chat together and waits for approval — this is what stands in forscripts/release.sh’s own interactive review in step 4, since the script can’t assemble a preview of the final notes until after it rotates the CHANGELOG itself. -
Run
scripts/release.sh— it refuses to start with untracked files in the working tree (it stages everything withgit add -A, so a stray file would land in the release commit); commit, delete or.gitignorethem first.--dry-runruns the local checks and shows the notes the release would publish, in a throwaway worktree, without branching, committing, pushing or tagging; it skips the remote-tag and security-deferred checks, so a green dry run is not a green release. Before committing anything it shows the extracted release notes and waits for approval (Enter accepts, anything else aborts and deletes the release branch). Any other failure before the release commit (changelog assembly, a missing[Unreleased]section) removes the release branch the same way. Empty notes fail closed. Because you already reviewed the fragments and the drafted summary together in step 3,/releasepasses--yes(orRELEASE_ASSUME_YES=1) to stand in for that prompt; a run with no TTY and no flag fails closed. It also passes the summary approved in step 3 throughRELEASE_SUMMARY_FILE, an env varrelease-notes.shreads and inserts verbatim into the generated notes, right above the changelog section rather than below it — unset it to publish with no upgrade-urgency section, which is also what a human running the script directly does by not setting it (the script warns on stderr if a previous release exists and nothing was set). The script also refuses a version whose tag already exists on the remote, or thatRELEASE_PUBLISHED_CHECK(an optional command you set, such as acurlagainst your registry) reports as already published. That command exits 0 for “published”, 1 for “not published”, and anything else for “could not tell”. An unreachable remote, or a check that could not tell, fails closed unlessRELEASE_ALLOW_OFFLINE=1. The comment aboverefuse_if_publishedin the script has a copy-paste example. It then assembles changelog fragments intoCHANGELOG.md, bumps version in all version-bearing files, creates achore/release-{version}branch with achore: release vX.Y.Zcommit that already carries the approved notes — there is no follow-up commit to add the summary afterward -
MR → merge → tag by hand. The release goes through a branch and MR like every other change. After it merges:
glab ci list --ref main --per-page 5 # confirm the merged commit's own pipeline is greengit checkout main && git pullgit tag vX.Y.Z && git push origin vX.Y.Zglab release create vX.Y.Z --notes-file docs/releases/vX.Y.Z.mdWhy by hand: see Why tagging is manual below.
git tag requires push access to the repository (or a protected-tag exception),
which any Maintainer running the release already has — no separate credential.
Publishing artifacts
Section titled “Publishing artifacts”Tagging is not the end of a release if the project ships something other people install.
A tag-triggered publish stage turns the tag into packages and images, and it needs no
long-lived registry token for PyPI or npm.
Publishing is permanent. PyPI and npm never let you replace or reuse a published
version, and a pushed image tag is what operators pull. Every publish job below runs
only on a final release tag (v1.2.3, matched by /^v[0-9]+\.[0-9]+\.[0-9]+$/), so
a pre-release tag such as v1.2.3-rc.1 publishes nothing to a real registry. Any tag
that does match publishes for real, so do not push one to “try it”.
Which targets? Publish only what you ship:
| Artifact | Target | Credential |
|---|---|---|
| Python package | PyPI | None stored: Trusted Publishing over GitLab OIDC |
| npm package | npm | None stored: trusted publishing over OIDC, which also generates provenance |
| Container image or Helm OCI chart | GitLab container registry | CI_REGISTRY_USER / CI_REGISTRY_PASSWORD, supplied by GitLab per job |
| Container image or Helm OCI chart | GHCR (ghcr.io) |
A token you store, because GHCR does not accept GitLab OIDC |
Choosing a registry
Section titled “Choosing a registry”- GitLab registry only when the project’s home is GitLab. A public project’s registry already allows anonymous pulls, it costs nothing to set up, and the credential is per job.
- GHCR when GitHub is the project’s public face: the read-only mirror (see
Publishing to GitHub) is where people find it, and
its package list and links should point at images beside it. The trade-off is one
stored, masked, protected
GHCR_TOKENvariable (a token withwrite:packages) to rotate. - Both is common for a public project: GitLab stays the source of truth and the CI cache, GHCR is what the GitHub side links to. Push the same build to both so the two never drift.
Pull by digest or by an immutable version tag in anything that deploys, never latest.
Trusted Publishing to PyPI
Section titled “Trusted Publishing to PyPI”PyPI Trusted Publishing swaps a GitLab-signed OIDC token for a short-lived upload
token, so no API token sits in CI/CD variables to leak or rotate. twine does the
exchange itself when no token is given.
Platform limit: PyPI supports GitLab.com projects only, not self-managed GitLab
instances. On a self-managed instance, store a project-scoped PyPI API token as a masked,
protected variable and pass it as TWINE_PASSWORD with TWINE_USERNAME=__token__.
- On PyPI, open the project’s Publishing settings (or Add a pending publisher
for a package that does not exist yet) and add a GitLab publisher: namespace,
project name, top-level pipeline file path (
.gitlab-ci.yml), and, if you use one, the job’senvironmentname. - In
.gitlab-ci.yml, give the job anid_tokensentry with audiencepypiand runtwine upload.
publish-pypi: stage: publish image: python:3.12-slim needs: [release-pipeline-gate] rules: - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/' environment: pypi # must match the environment named on PyPI, if you set one id_tokens: PYPI_ID_TOKEN: aud: pypi script: # python -m build takes the version from pyproject.toml, not from the tag: refuse a mismatch. - | PKG_VERSION="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")" test "$PKG_VERSION" = "${CI_COMMIT_TAG#v}" || { echo "pyproject version $PKG_VERSION != tag ${CI_COMMIT_TAG#v}"; exit 1; } - python -m pip install -U build twine - python -m build # With no token set, twine uses Trusted Publishing. - twine upload dist/*The version check reads a static [project] version. If your project computes its
version, compare against what python -m build actually produced instead.
To rehearse the path, add a TestPyPI publisher (a separate trusted-publisher entry on test.pypi.org) and a second job that runs only for pre-release tags and never touches the real index:
publish-testpypi: stage: publish image: python:3.12-slim needs: [release-pipeline-gate] rules: - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+-/' id_tokens: TESTPYPI_ID_TOKEN: aud: testpypi script: - python -m pip install -U build twine - python -m build - twine upload --repository testpypi dist/*TestPyPI also refuses a repeated version, so bump the pre-release number for each rehearsal.
Trusted publishing to npm
Section titled “Trusted publishing to npm”npm accepts the same shape: configure a GitLab trusted publisher on the package’s npm
settings page, expose two OIDC tokens with id_tokens, and run a plain npm publish.
Trusted publishing generates provenance automatically for a public repository and
package, so the --provenance flag is not needed. It requires npm CLI 11.5.1 or later
and Node.js 22.14.0 or later; the example installs a current npm to be sure. The
trusted-publisher fields are namespace, project, top-level CI file path and an optional
environment name. Check
npm’s trusted publishing documentation
for changes to the audiences and fields.
Four npm details that fail a first release:
- Platform limit: trusted publishing works only from cloud-hosted runners (GitLab.com shared runners), not self-hosted runners. On a self-hosted runner, publish with a granular access token stored as a masked, protected variable.
- Allowed actions:
npm stage publishis always allowed, and plainnpm publishis a separate permission you must enable on the trusted publisher. Without it the job below is refused; the alternative is to stage each release and approve it with 2FA. - A new package needs a first publish by other means. The trusted publisher is set on an existing package’s settings page, so expect to publish the first version with a token, then switch to OIDC. npm’s page does not describe this case, so confirm it for your package.
- A new trusted-publisher configuration expires if it has no successful publish within 2 days. Create it just before the release, not weeks ahead.
publish-npm: stage: publish image: node:22.14 needs: [release-pipeline-gate] rules: - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/' id_tokens: NPM_ID_TOKEN: aud: "npm:registry.npmjs.org" SIGSTORE_ID_TOKEN: aud: sigstore script: # npm publishes the version in package.json, not the tag: refuse a mismatch. - | PKG_VERSION="$(node -p "require('./package.json').version")" test "$PKG_VERSION" = "${CI_COMMIT_TAG#v}" || { echo "package.json version $PKG_VERSION != tag ${CI_COMMIT_TAG#v}"; exit 1; } - npm install -g npm@^11.5.1 - npm ci - npm publish --access publicImages and charts to GitLab and GHCR
Section titled “Images and charts to GitLab and GHCR”Build once with kaniko (the same no-privileged-mode approach ci/docker.yml uses) and
push to both registries in one invocation. Set GHCR_TOKEN as a masked, protected
CI/CD variable and GHCR_USER to the account that owns the package.
publish-image: stage: publish image: name: gcr.io/kaniko-project/executor:debug@sha256:2562c4fe551399514277ffff7dcca9a3b1628c4ea38cb017d7286dc6ea52f4cd entrypoint: [""] needs: [release-pipeline-gate] rules: - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/' script: - mkdir -p /kaniko/.docker - GITLAB_AUTH="$(printf '%s:%s' "$CI_REGISTRY_USER" "$CI_REGISTRY_PASSWORD" | base64 | tr -d '\n')" - GHCR_AUTH="$(printf '%s:%s' "$GHCR_USER" "$GHCR_TOKEN" | base64 | tr -d '\n')" - printf '{"auths":{"%s":{"auth":"%s"},"ghcr.io":{"auth":"%s"}}}' "$CI_REGISTRY" "$GITLAB_AUTH" "$GHCR_AUTH" > /kaniko/.docker/config.json - > /kaniko/executor --context "$CI_PROJECT_DIR" --dockerfile "$CI_PROJECT_DIR/Dockerfile" --destination "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG" --destination "ghcr.io/acme/app:$CI_COMMIT_TAG"
publish-chart: stage: publish image: name: alpine/helm:3.16.3 entrypoint: [""] needs: [release-pipeline-gate] variables: CHART_REPO: "acme/charts/app" rules: - if: '$CI_COMMIT_TAG =~ /^v[0-9]+\.[0-9]+\.[0-9]+$/' script: - apk add --no-cache bash curl jq # Refuses a version that a published chart would outrank (scripts/check-chart-registry.sh). - bash scripts/check-chart-registry.sh --candidate "${CI_COMMIT_TAG#v}" - helm package helm --version "${CI_COMMIT_TAG#v}" --app-version "${CI_COMMIT_TAG#v}" - echo "$CI_REGISTRY_PASSWORD" | helm registry login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" --password-stdin - echo "$GHCR_TOKEN" | helm registry login ghcr.io -u "$GHCR_USER" --password-stdin - helm push "app-${CI_COMMIT_TAG#v}.tgz" "oci://$CI_REGISTRY_IMAGE/charts" - helm push "app-${CI_COMMIT_TAG#v}.tgz" oci://ghcr.io/acme/chartsReplace acme/app and acme/charts with your own namespace, and make the name: in
helm/Chart.yaml match the packaged file name (app here). The chart is published as
ghcr.io/acme/charts/app, so set ci/helm.yml’s CHART_REPO to acme/charts/app (and
GHCR_HOST if the host differs); that is what its registry-drift job and upgrade drill
read. check-chart-registry.sh reads the same CHART_REPO, and may need other tools
or variables its header lists (CHART_DEFAULT_IMAGES, IMAGE_REGISTRY_HOST).
Pin the job images by digest. Only the kaniko image above is pinned. Pin
python, node and alpine/helm the same way before use
(image:tag@sha256:<digest>, resolved with docker buildx imagetools inspect), as
ci/docker.yml does. scripts/check-ci-image-pins.py fails an unpinned reference in
.gitlab-ci.yml or ci/*.yml.
Signing is opt-in. ci/image-signing.yml is off by default and commented out of
.gitlab-ci.yml. To sign what you push, include it, set SIGN_IMAGE_REFS (for example
"$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"), and edit its image-sign-attest job in
ci/image-signing.yml itself to stage: publish and needs: [publish-image, release-pipeline-gate] so the image exists before it is signed. From 0.8, do not
override the job in your own .gitlab-ci.yml: make check-release-ci-file fails a job
defined in two files. If you already have such an override, move it into
ci/image-signing.yml. It logs in to
$CI_REGISTRY only, so a GHCR ref needs its own docker login step first. Its header
also has a snippet that signs a Helm chart with the same cosign pin.
Wiring it in
Section titled “Wiring it in”- Add
publishto thestages:list in.gitlab-ci.yml, afterdeployif you have one. A tag pipeline only runs jobs whoserules:match the tag, so branch and MR pipelines stay unchanged. - Every job above has
needs: [release-pipeline-gate], which stops a tag whose commit failed its own branch pipeline. Stage order alone is not that promise: a job with noneeds:waits only for earlier stages, and a tag pipeline is separate from the branch pipeline. On the Full variant, where you tagproduction, setRELEASE_PIPELINE_REF=productionfor that gate (see the header ofscripts/check-release-pipeline.py), or it checksmain’s pipeline and every publish job that needs it fails. Also change the script’sALWAYS_REQUIREDto jobs that run onproductionpipelines: its defaults,version-lockstepandosv-scan, run only onmainand MRs, so the gate would refuse every tag. - From 0.8 (ships in 0.8, macrodream/blueprint#315), the gate judges that pipeline job by job: every job must be
success, a failedallow_failure: truejob included, unless the script’sEXEMPT_JOBSnames it, and every job in itsALWAYS_REQUIREDmust be present. It fails closed when it cannot read the forge. It needs aRELEASE_GATE_TOKEN(aread_apiproject access token, masked and protected, withv*tags protected); from 0.8 it no longer falls back toCI_JOB_TOKEN, which cannot read the project’s pipelines. It also checks the CI variables a pipeline variable could override (ships in 0.8, macrodream/blueprint#323): it sends no token to an API URL that is not https onCI_SERVER_HOST, and it refuses whenCI_PROJECT_IDis notCI_PROJECT_PATH, whenRELEASE_PIPELINE_REFis neither the default branch nor a protectedproductionbranch, or when the tag does not point atCI_COMMIT_SHAorCI_COMMIT_SHAis not the commit the job checked out. It refuses proxy and CA variables (HTTPS_PROXY,SSL_CERT_FILE, …) that would reroute the token. Pin the forge host and project in the script’sTRUSTED_SERVER_HOSTSandTRUSTED_PROJECT_PATH(ships in 0.8, macrodream/blueprint#334: the template reset empties Blueprint’s own, andmake customizeasks for yours), and give the token the environment scoperelease-gate, so only the gate job gets it. Each refusal and its fix:docs/harness/release-pipeline-gate.mdin the repository. make check-release-ci-file(ships in 0.8; pre-push, and therelease-pipeline-ci-fileMR job) fails a tag-triggered job whoseneeds:does not strictly name the gate, so a new publish job cannot drop it unnoticed.- Dry-run before the first real tag. None of this YAML has run against your project.
Rehearse with the TestPyPI job and a pre-release tag, build the image and chart under
a throwaway name (change
--destinationand the chartname:) from a branch, and fix what breaks while nothing permanent has been published. These jobs otherwise run for the first time at the tag, whichscripts/check-tag-only-jobs.shreports as “unproven”.
GitLab Flow
Section titled “GitLab Flow”The template supports two branching models. Choose one during setup; the rules for both
are in AGENTS.md (Forbidden operations) and the full explainer in
docs/harness/branching-model.md:
- Simple (tag on main):
feature branch → MR → main → tag. Best for projects that deploy continuously or don’t have a staging/production split. - Full (with production branch):
feature branch → MR → main (staging) → merge to production → tag. Best for projects with a formal release train. Tag onproductioninstead ofmainif you use this variant.
Why tagging is manual
Section titled “Why tagging is manual”The short answer: it’s two commands, and the automated version silently never ran.
Between the lines:
- An earlier version of this template had CI jobs that tagged and published once a
chore: release vX.Y.Zcommit reachedmain. They matched the commit message against/^chore: release v/. - GitLab’s rule regexes treat
^as the start of the whole message, not of a line. A real merge commit starts withMerge branch '…' into 'main'and puts the MR title on line two — so the rule never matched. On the v0.5.0 cut the job simply didn’t run. - It also needed a masked, protected
RELEASE_TOKENvariable: one more secret to set up and keep valid. - The jobs were retired in macrodream/blueprint#56. Tagging by hand matches the
releaseskill’s own Step 5, and how the sibling project TruePPM releases.