All jobs

Add release-plz to a Rust Library

Yes. An agent configures release-plz for a crate, adds a workflow that opens a release PR and publishes on merge, dry-runs the bump in its sandbox and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the crate into its own cloud sandbox and reads how releases happen today. In a library like rust-itertools/itertools, Cargo.toml declares version 0.15.0, rust-version = "1.63.0", one dependency on either with default features off, features use_std and use_alloc, and ten [[bench]] targets with harness = false. CHANGELOG.md is written by hand, with Breaking, Added, Changed and Notable Internal Changes sections per version and a pull request number after each line. .github/workflows/ci.yml runs on pull_request and merge_group with jobs for clippy across four feature sets, cargo doc with warnings denied, an MSRV check on 1.63.0 through cargo-no-dev-deps, tests, Miri, cargo fmt --check and obi1kenobi/cargo-semver-checks-action; coverage.yml uploads cargo-llvm-cov output. There is no release or publish workflow, no cargo-release or release-plz configuration, and the README's install snippet names 0.15.0 in plain text. Publishing is somebody running cargo publish from a laptop.

It writes release-plz.toml at the repository root with the settings that match what the project already does. semver_check = true so release-plz decides between a patch and a breaking bump by running cargo-semver-checks, the same tool CI runs on every pull request; changelog_update = true so each release pull request edits CHANGELOG.md; git_release_enable = true so a GitHub release is created with the changelog entry as its body; and dependencies_update = false so a release never silently refreshes Cargo.lock. Under [changelog] it writes a git-cliff body template whose section headings are the ones the file already uses, with commit parsers that put commits mentioning a breaking change under Breaking and everything else under Changed, and it keeps the existing header so the top of the file reads the same as before.

Then it adds .github/workflows/release-plz.yml on push to the default branch, with a concurrency group so two merges cannot race, fetch-depth: 0 on checkout because the tool reads tags and history, dtolnay/rust-toolchain@stable as the other workflows use, and two jobs: release-plz release-pr, which opens or updates one pull request carrying the version bump and the changelog entry, and release-plz release, which runs after a merge that changed the version and publishes to crates.io and tags the commit. The publish job takes CARGO_REGISTRY_TOKEN from a repository secret, and the pull request job takes a token from a GitHub App or a personal token stored as RELEASE_PLZ_TOKEN, because a pull request opened with the default GITHUB_TOKEN does not trigger ci.yml, and the whole point is that the release pull request runs the same checks as any other.

It proves the pieces in the sandbox before opening anything. cargo install release-plz, then release-plz update on a throwaway branch, which bumps Cargo.toml and rewrites the changelog locally without touching the remote, so the diff shows exactly what the first release pull request would contain and whether cargo-semver-checks called the next version 0.15.1 or 0.16.0. cargo publish --dry-run shows the crate packages cleanly with the benches/ and examples/ directories included or excluded as Cargo.toml says. cargo test --all-features and cargo fmt --check run unchanged. The throwaway branch is deleted and only the configuration and the workflow are committed.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Set up release-plz for this Rust library. Read Cargo.toml, CHANGELOG.md, README.md, CONTRIBUTING.md and every workflow under .github/workflows first, and describe how releases happen today. Write release-plz.toml with semver checks on, changelog updates on, a GitHub release on, dependency updates off, and a changelog template whose section headings match the existing CHANGELOG.md. Add a release-plz workflow on push to the default branch with a concurrency group, full-depth checkout and two jobs, release-pr and release, reading CARGO_REGISTRY_TOKEN and a RELEASE_PLZ_TOKEN that lets the release pull request trigger CI. Do not change the crate version yourself. In your sandbox install release-plz, run release-plz update on a throwaway branch to show the bump and changelog entry it would produce, run cargo publish --dry-run, cargo test --all-features and cargo fmt --check, then discard the throwaway branch and open a pull request with the configuration, the workflow, a README note on the secrets to create, and the command output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request adding release-plz.toml and .github/workflows/release-plz.yml, plus a short section in CONTRIBUTING.md on the two secrets and the new release flow: merge the release pull request and the publish happens. Cargo.toml and CHANGELOG.md are unchanged in the pull request itself; the description shows the diff release-plz update produced in the sandbox so a reviewer can see the bump the tool chose and how the generated changelog entry sits under the existing headings.

The run's record keeps the release-plz update output, the cargo publish --dry-run packaging list and the test and format runs, so a reviewer knows the configuration parses, the semver check reached a decision, and the crate still packages, without installing anything.

Before merging, a reviewer creates the crates.io token with publish scope for this crate only, creates the GitHub App or personal token for the pull request job, checks that branch protection allows the release job to push a tag, and decides whether the README install snippet should be updated by hand in each release pull request or dropped in favour of the docs.rs badge.

Run it on every crate ready for automated releases

A maintainer hands this off from the terminal once per crate: one POST /o/{org}/sessions with this body and the repository in resources, and the review happens on the pull request. A team that owns several crates sends one request per repository, each in its own sandbox with its own changelog format read first, and compares the resulting configurations side by side.

After the merge the recurring work is release-plz's own: every push to the default branch updates the release pull request, and merging it publishes. An agent run is only needed again when the changelog format or the publish flow changes, which a developer starts the same way with a prompt describing the change.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Release automation is configuration that is hard to test without releasing. The sandbox is where release-plz update can run against a throwaway branch and show the exact bump and changelog entry, where cargo publish --dry-run can prove the package builds, and where none of that reaches crates.io or the remote. The pull request arrives with those outputs in its description, so the first real release is the second time anyone has seen what the tool does.

The same body runs against every crate an organisation maintains, and each pull request keeps the full record. A maintainer reads the generated changelog entry next to the hand-written one above it and decides on the template with evidence, not a guess about what git-cliff will produce.

Frequently asked questions

Will release-plz publish without anyone looking?

No. It opens a pull request with the version bump and changelog entry, and publishing happens only when a maintainer merges it. Nothing is published on an ordinary merge that leaves the version alone.

How does it choose patch or minor?

With semver_check = true it runs cargo-semver-checks against the last published version and bumps the minor version for a 0.x crate when the public API broke, otherwise the patch version. CI already runs the same tool on pull requests, so the two never disagree about what counts as breaking.

Can we keep editing the changelog by hand?

Yes. The release pull request is an ordinary branch; a maintainer edits the generated entry, reorders lines or adds a note before merging, and release-plz keeps those edits. The template only decides the first draft and its headings.

Why a separate token for the release pull request?

Because GitHub does not run workflows on pull requests opened by the default GITHUB_TOKEN, so the release pull request would merge without clippy, Miri or the MSRV check having run. A GitHub App token or a personal token with contents and pull_requests write scope makes it a normal pull request to CI.

What about the version in the README?

release-plz does not rewrite README text. The pull request notes that the itertools = "0.15.0" snippet needs a hand edit in each release pull request, or a switch to a version-free install line, and leaves that choice to the maintainers.

More Rust library jobs

More jobs like this: Hand off a long task

Keep reading