Skip to content

release-plz

Deprecated

No estate repository uses release-plz any more. Rust crates release through colophon, which proposes the release MR and tags, plus rust-release, which gates that MR with cargo-semver-checks and publishes to crates.io on the tag. Wiki spec 0116 records the move. The component stays for anyone pinning it, and is not maintained ahead of need.

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"

Toolchain resolution

Both jobs export RUSTUP_TOOLCHAIN, resolved from the consumer's own rust-toolchain.toml (falling back to whatever rustup already resolves, and to nothing at all if the repo pins no toolchain).

This exists because release-plz runs cargo package against copies of each crate in a temp directory, where rust-toolchain.toml does not apply. Left alone, rustup falls back to its default toolchain — and a runner whose RUSTUP_HOME is a fresh shared cache has no default, so the job fails with rustup could not choose a version of cargo to run while every in-repo cargo job on the same runner passes.

The component sets the environment variable rather than running rustup default, because RUSTUP_HOME may be shared across a runner fleet: writing a default would mutate state other projects race on, and consumers pin different toolchains.

Inputs

Input Type Default Description
image string "rust:1.97-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.
github_token string "$GITHUB_COM_TOKEN" GitHub token for cargo-binstall's release lookups, exported as GITHUB_TOKEN (also covers binstalls in extra_before_script). Anonymous lookups share a 60-an-hour limit per IP, which one batch of release jobs on a shared runner exhausts. Unset or empty means anonymous.
extra_before_script string "" Shell snippet prepended to before_script.
cache_prune_days number 7 When the runner exports RUST_CACHE_DIR, the job builds in a target directory beneath it keyed by compiler (rustc -vV) and libc, and removes keyed directories no job has used for this many days. Give every Rust component in a project the same value. No effect without RUST_CACHE_DIR. Wiki spec 0106. A key last used before a newer key appeared goes after one idle day regardless (wiki spec 0119).

Usage

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

See also