# 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 Rush](https://cloud.getrush.ai/run/add-release-plz/rust-library/). Opens 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`

```json
{
  "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.

## 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

- [Add cargo-semver-checks to a Rust Library's CI](https://getrush.ai/run/add-semver-checks/rust-library/)
- [Write Property-Based Tests for a Rust Library](https://getrush.ai/run/write-property-tests/rust-library/)
- [Add cargo-deny to a Rust Library Workspace](https://getrush.ai/run/add-cargo-deny/rust-library/)

## More jobs like this: Hand off a long task

- [Add a Release Workflow for a Chrome Extension](https://getrush.ai/run/add-release-workflow/chrome-extension/)
- [Add a GitHub Release Workflow With CPack Packages to a CMake Project](https://getrush.ai/run/add-release-workflow/cmake/)
- [Add a Release Workflow to an Elixir Library](https://getrush.ai/run/add-release-workflow/elixir/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
