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.tomlversion is ahead of crates.io), publishes all crates in dependency order, creates thev{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¶
releaser-pleaser— the Go-track equivalent for Conventional-Commits projects.- Explanation: release automation
- Specs:
0013-release-plz-split-jobs-v0.10.3,0015-release-plz-order-pr-after-release-v0.10.4,0016-release-plz-checkout-pinned-sha-v0.10.6