Skip to content

release-plz

Rust release driver. On every push to the default branch it runs two idempotent steps, as two separate jobs:

  • release-plz:pr — opens / updates the Release MR with the next unified version + per-crate changelogs (Conventional Commits).
  • release-plz:release — when the Release MR has been merged (Cargo.toml version is ahead of crates.io), publishes all crates in dependency order, creates the v{version} tag, and the GitLab release. No-op when there's nothing to release.

Why two jobs, not two script lines in one job: release-plz release-pr mutates the working tree (checks out the Release MR branch, git reset --hard, rebases). If release then ran in the same shell, it would read cargo metadata against that mutated tree, see the pre-bump version, and silently skip the publish. Each job gets its own clean checkout of $CI_COMMIT_SHA, so release always sees the just-merged, version-bumped tree. pr runs needs: [release-plz:release] (optional: true) — ordered after release within the stage, so on the pipeline that merges a Release MR, pr analyses the post-release state to compute the next version rather than a spurious mid-release one.

Token requirement

token (default $RELEASE_PLZ_TOKEN) must not be $CI_JOB_TOKEN — a tag pushed with CI_JOB_TOKEN does not trigger downstream tag pipelines (GitLab loop-prevention), so a release-asset job would never fire. A CARGO_REGISTRY_TOKEN CI/CD variable is also needed for cargo publish.

Each job re-attaches to the default branch (CI checks out a detached HEAD) and points origin at a remote authenticated with the release token, so release-plz can push the Release MR branch and the version tag.

Jobs

Job What it runs
release-plz:pr release-plz release-pr --forge gitlab --git-token "$RELEASE_PLZ_TOKEN_RUNTIME"
release-plz:release release-plz release --forge gitlab --git-token "$RELEASE_PLZ_TOKEN_RUNTIME"

Inputs

Input Type Default Description
image string "rust:1.83-bookworm" Rust image used to bootstrap binstall + run release-plz.
stage string release GitLab CI stage.
if string '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' Gating rules:if:. Fires on the default branch only.
forge string "gitlab" release-plz --forge flag (defaults to GitHub upstream, errors on gitlab.com without this).
token string "$RELEASE_PLZ_TOKEN" Token for git push + GitLab API + tag. Needs api + write_repository; must not be $CI_JOB_TOKEN.
release_plz_version string "" Optional version constraint for cargo binstall release-plz. Empty = latest.
extra_before_script string "" Shell snippet prepended to before_script.

Usage

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]

See also