Skip to content

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:

  1. /pre-release full at feature freeze; fix the blockers; run it once more before tagging.
  2. /release opens a chore/release-X.Y.Z branch and MR.
  3. After it merges and its pipeline is green: git tag, push the tag, glab release create.

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 only

This 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.

/release [version]

The /release command handles the full flow:

  1. Determine version — reads CHANGELOG.md [Unreleased] and suggests semver (patch for fixes only, minor for added features, major for breaking changes)

  2. 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 into tooling-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.

  3. Draft and approve the summary and notes together. Before running anything, /release drafts 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. /release first 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.0 after 1.1.0 and a bug-fix-only 1.1.1 has baseline 1.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. /release asks 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. /release shows you both that draft and the rendered changelog fragments in chat together and waits for approval — this is what stands in for scripts/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.

  4. Run scripts/release.sh — it refuses to start with untracked files in the working tree (it stages everything with git add -A, so a stray file would land in the release commit); commit, delete or .gitignore them first. --dry-run runs 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, /release passes --yes (or RELEASE_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 through RELEASE_SUMMARY_FILE, an env var release-notes.sh reads 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 that RELEASE_PUBLISHED_CHECK (an optional command you set, such as a curl against 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 unless RELEASE_ALLOW_OFFLINE=1. The comment above refuse_if_published in the script has a copy-paste example. It then assembles changelog fragments into CHANGELOG.md, bumps version in all version-bearing files, creates a chore/release-{version} branch with a chore: release vX.Y.Z commit that already carries the approved notes — there is no follow-up commit to add the summary afterward

  5. 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 green
    git checkout main && git pull
    git tag vX.Y.Z && git push origin vX.Y.Z
    glab release create vX.Y.Z --notes-file docs/releases/vX.Y.Z.md

    Why 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.

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
  • 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_TOKEN variable (a token with write: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.

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__.

  1. 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’s environment name.
  2. In .gitlab-ci.yml, give the job an id_tokens entry with audience pypi and run twine 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.

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 publish is always allowed, and plain npm publish is 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 public

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/charts

Replace 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.

  • Add publish to the stages: list in .gitlab-ci.yml, after deploy if you have one. A tag pipeline only runs jobs whose rules: 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 no needs: waits only for earlier stages, and a tag pipeline is separate from the branch pipeline. On the Full variant, where you tag production, set RELEASE_PIPELINE_REF=production for that gate (see the header of scripts/check-release-pipeline.py), or it checks main’s pipeline and every publish job that needs it fails. Also change the script’s ALWAYS_REQUIRED to jobs that run on production pipelines: its defaults, version-lockstep and osv-scan, run only on main and 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 failed allow_failure: true job included, unless the script’s EXEMPT_JOBS names it, and every job in its ALWAYS_REQUIRED must be present. It fails closed when it cannot read the forge. It needs a RELEASE_GATE_TOKEN (a read_api project access token, masked and protected, with v* tags protected); from 0.8 it no longer falls back to CI_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 on CI_SERVER_HOST, and it refuses when CI_PROJECT_ID is not CI_PROJECT_PATH, when RELEASE_PIPELINE_REF is neither the default branch nor a protected production branch, or when the tag does not point at CI_COMMIT_SHA or CI_COMMIT_SHA is 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’s TRUSTED_SERVER_HOSTS and TRUSTED_PROJECT_PATH (ships in 0.8, macrodream/blueprint#334: the template reset empties Blueprint’s own, and make customize asks for yours), and give the token the environment scope release-gate, so only the gate job gets it. Each refusal and its fix: docs/harness/release-pipeline-gate.md in the repository.
  • make check-release-ci-file (ships in 0.8; pre-push, and the release-pipeline-ci-file MR job) fails a tag-triggered job whose needs: 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 --destination and the chart name:) from a branch, and fix what breaks while nothing permanent has been published. These jobs otherwise run for the first time at the tag, which scripts/check-tag-only-jobs.sh reports as “unproven”.

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 on production instead of main if you use this variant.

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.Z commit reached main. 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 with Merge 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_TOKEN variable: one more secret to set up and keep valid.
  • The jobs were retired in macrodream/blueprint#56. Tagging by hand matches the release skill’s own Step 5, and how the sibling project TruePPM releases.