# Add cargo-semver-checks to CI for a Rust Library

Yes. An agent adds a cargo-semver-checks job to a crate's GitHub Actions workflow, runs it against the published baseline in its sandbox and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-cargo-semver-checks-to-ci/rust-library/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the crate and its workflow before touching either, because the right job depends on how the crate is already tested. In a library like tokio-rs/bytes, `Cargo.toml` declares `bytes` at `version = "1.12.1"`, edition 2021 and `rust-version = "1.57"`, with a `std` feature on by default and two optional dependencies, `serde` and `extra-platforms` (the `portable-atomic` crate under another name). `.github/workflows/ci.yml` runs on pull requests and pushes to `master` and on a weekly cron, sets `RUSTFLAGS: -Dwarnings`, and has eleven jobs: `rustfmt`, `minrust` with `cargo hack check --feature-powerset --optional-deps --rust-version`, `stable` on four runners through `ci/test-stable.sh`, a pinned `nightly`, `panic-abort`, `cross` on five targets, `no-std` on thumbv6m and thumbv7m, `tsan`, `miri`, `loom`, and `publish_docs`, whose `needs` list is what gates the docs push. A `clippy` job is commented out with a TODO. `Cargo.lock` is in `.gitignore`, and the comment at the top of `Cargo.toml` says a release is a `CHANGELOG.md` entry and a `v1.x.y` tag. Nothing checks that a change to a public type is allowed by the version it will ship under.

It adds one job, `semver`, to the same workflow. The job checks out the crate, installs stable Rust the way the other jobs do, and runs `obi1kenobi/cargo-semver-checks-action@v2` with `feature-group: all-features` so the `serde` and `extra-platforms` APIs are compared too, not only the default feature set. The baseline is the version of `bytes` on crates.io, which is what the action compares against when no other baseline is given; the pull request explains that the first run after a release therefore compares against the version just published. The job is added to `publish_docs`'s `needs` list so a breaking change blocks the docs push the same way a failing test does, and it is left out of the `schedule` run's concerns, because the weekly cron exists to catch toolchain drift, not API drift.

Then the agent runs the check itself. It installs the tool with `cargo install cargo-semver-checks --locked` and runs `cargo semver-checks check-release --all-features` in the crate, which downloads the published 1.12.1, builds rustdoc JSON for both and reports every lint by name: a removed public item, a changed trait bound, a struct that lost `#[non_exhaustive]`. On an unchanged checkout the report is empty, and the agent records the tool version and the toolchain it ran under. It also makes a deliberate break on a scratch branch it never pushes, such as removing a public method from `src/bytes.rs`, to see the tool fail with the lint it expects, and shows that output in the pull request as the proof the job would catch a real break.

The pull request also records the two choices a maintainer may want to change. `rust-version` is 1.57, but the check runs on current stable, since `cargo-semver-checks` needs a modern toolchain to produce rustdoc JSON; the job therefore does not touch `minrust`. And because the crate's release process is a tag and a changelog, the agent adds a short note to `CHANGELOG.md`'s unreleased section and nothing to the release steps, so the check is a gate on pull requests, not a step a release engineer has to remember.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add cargo-semver-checks to this Rust library's CI. Read Cargo.toml, every workflow under .github/workflows, any ci/ scripts they call, clippy.toml and CHANGELOG.md first. Add one job to the existing CI workflow that runs the cargo-semver-checks GitHub Action against the crate's published version on crates.io with all features enabled, and add it to the needs list of whichever job aggregates the others. Do not change the minimum supported Rust version job. Install cargo-semver-checks in the sandbox and run check-release with all features on the current checkout; then, on a scratch branch you never push, remove one public item and run it again to show the failure it reports. Put both outputs in the pull request, note the tool and toolchain versions, add a line to the changelog's unreleased section, and open a pull request.",
  "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 that changes `.github/workflows/ci.yml` and `CHANGELOG.md` and nothing else. The diff adds the `semver` job and one line to the `needs` list, and the description shows the clean `check-release` output on the current code, the failing output from the deliberate break with the lint name and the file and line it pointed at, and the versions of `cargo-semver-checks` and `rustc` it used.

The run's record keeps every command: the install, both check runs and the `git diff` of the scratch break, so a reviewer can see the job was exercised rather than pasted in. The pull request says what it does not do: it does not pin a baseline revision, and it does not bump the crate version.

Before merging, a reviewer opens the workflow run on the pull request itself and confirms the new job passes there, then reads the job's log once to see which baseline it fetched. From then on a pull request that removes or changes a public item fails the `semver` job with the same lint names the description shows.

## Run it on every Rust crate

A maintainer with several crates hands this off from the terminal once per repository: one `POST /o/{org}/sessions` with this body and the repository in `resources`. Each run reads that crate's own workflow and adds the job in its style, so a crate that aggregates with a `ci-success` job gets the dependency there, and one with a single `test` job gets a sibling. A `request_id` that is a UUID v5 of the repository name makes a retried request return the run it already started.

For a workspace with several published crates, the prompt names the package, and the job runs `cargo semver-checks` with `--package` for that one, since each has its own baseline on crates.io.

## Why run it on Rush?

Semver breaks are found by comparing two rustdoc builds, which is slow to do by hand and easy to skip before a release. The agent does the comparison in its own sandbox with the real published baseline, runs it twice to prove the job both passes and fails, and leaves the commands and their output in the run's record.

The result is a one-job pull request a maintainer can read in a minute, with the proof attached, instead of a note to themselves to set it up before the next minor release.

## Frequently asked questions

### What does the job compare against?

The latest version of the crate on crates.io, which the action fetches when no other baseline is given. After a release the next pull request is compared against the version just published, which is the comparison that matters for the following version number.

### Does this change my minimum supported Rust version?

No. The `minrust` job keeps checking with `rust-version` 1.57, and the `semver` job runs on current stable, which `cargo-semver-checks` needs for rustdoc JSON. The two jobs are independent and the pull request says so.

### Will it flag a change behind an optional feature?

Yes, because the job runs with all features. The `serde` implementations and the `extra-platforms` build are part of the public API that downstream crates enable, so a change there is compared like any other.

### What if I intend to make a breaking change?

Bump the major version in `Cargo.toml` in the same pull request. `cargo-semver-checks` reads the version you are about to publish, and a major bump makes the removed item allowed. The job then passes and the changelog entry documents the break.

### Does the agent push the deliberate break anywhere?

No. The break lives on a scratch branch inside the sandbox, run once to capture the failure output, and only that output appears in the pull request. The branch the pull request comes from contains the workflow and changelog edits only.

## More Rust library jobs

- [Label Feature-Gated Items on docs.rs for a Rust Library](https://getrush.ai/run/add-docs-rs-metadata/rust-library/)
- [Add release-plz to a Rust Library](https://getrush.ai/run/add-release-plz/rust-library/)
- [Add cargo-semver-checks to a Rust Library's CI](https://getrush.ai/run/add-semver-checks/rust-library/)

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

- [Add ccache to a CMake Project's GitHub Actions Builds](https://getrush.ai/run/add-ccache-to-ci/cmake/)
- [Add Changesets to a TypeScript Library](https://getrush.ai/run/add-changesets/typescript-library/)
- [Add Checkov Scanning to a Terraform Module's CI](https://getrush.ai/run/add-checkov-to-ci/terraform/)

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