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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
More jobs like this: Hand off a long task
- Add ccache to a CMake Project's GitHub Actions Builds (CMake)
- Add Changesets to a TypeScript Library (TypeScript library)
- Add Checkov Scanning to a Terraform Module's CI (Terraform)