# Add cargo-semver-checks to a Rust Library's CI

Yes. An agent adds a cargo-semver-checks job to your crate's GitHub Actions CI so a pull request that breaks the public API fails before release.

[Run this on Rush](https://cloud.getrush.ai/run/add-semver-checks/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 repository into its own cloud sandbox and reads the crate's manifest and CI before it adds a job. In a crate like serde-rs/json, `Cargo.toml` names the package `serde_json` at version `1.0.154` with `rust-version = "1.71"` and `edition = "2021"`. The features matter for an API check: `default = ["std"]`, plus `alloc`, `preserve_order` (which swaps the `Map` representation for `indexmap`), `float_roundtrip`, `arbitrary_precision`, `raw_value` and `unbounded_depth`. The `[package.metadata.docs.rs]` table builds docs with `preserve_order`, `raw_value` and `unbounded_depth`, which tells the agent which feature set the maintainers treat as the documented public surface. `tests/crate/Cargo.toml` is a separate `serde_json_test` package that depends on the crate by path with `default-features = false`, used by the `build` job to check feature combinations.

Then it reads `.github/workflows/ci.yml`. The file runs on `push`, `pull_request`, `workflow_dispatch` and a nightly `schedule`, sets `permissions: contents: read` and `RUSTFLAGS: -Dwarnings`, and every job has `timeout-minutes: 45`. Its jobs are `test` (nightly on ubuntu and windows, one `cargo test` per feature), `build` (beta, `1.85.0` and `1.71.0`, plus stable on `aarch64-unknown-none` and windows, all through the test crate), `minimal` (`-Z minimal-versions`), `miri` on four targets, `clippy`, `doc` (`cargo docs-rs`), `fuzz` and `outdated`. Tools are installed with `dtolnay/install@cargo-docs-rs`, `dtolnay/install@cargo-fuzz` and `dtolnay/install@cargo-outdated`, and `clippy` and `outdated` are skipped on `pull_request`. None of these compares the public API against the last release.

The agent adds a `semver` job in the same style: `actions/checkout@v7`, `dtolnay/rust-toolchain@stable`, `dtolnay/install@cargo-semver-checks`, then `cargo semver-checks` twice, once with the default features and once with `--features preserve_order,raw_value,unbounded_depth` to match the docs.rs build. cargo-semver-checks downloads the latest published version of the crate from crates.io as the baseline, builds rustdoc JSON for both, and reports each change with its lint name, the item it affects and the version bump it would require. The job runs on `pull_request` and `workflow_dispatch` only: on a release commit the version in `Cargo.toml` is already ahead of the baseline, and on the nightly schedule the result would repeat the last pull request's. It gets the file's `timeout-minutes: 45` and nothing else that the other jobs do not have.

In the sandbox the agent runs the same two commands against the current `master` so the pull request shows what the check says today, and runs `cargo test` once to confirm the toolchain it installed builds the crate. If the baseline comparison reports a change, the pull request quotes it rather than silencing it; the agent adds no `[package.metadata.cargo-semver-checks]` configuration unless a lint fires on something the maintainers clearly intend, such as a feature-gated item, and then it says which lint and why.

## 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 GitHub Actions CI. Read Cargo.toml and the existing workflow first and follow the workflow's conventions for installing tools, permissions and timeouts. Add one job that compares the crate's public API against the latest published version on crates.io, with the default features and with the feature set the docs.rs metadata uses, and run it on pull requests only. Run the same checks in your sandbox against the current branch and quote the output in the pull request. Do not change any source file, feature or version, and do not add lint overrides unless a reported change is clearly intended, in which case explain it.",
  "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 on its own branch that changes one file, `.github/workflows/ci.yml`, adding the `semver` job after `outdated`. The description quotes the `cargo semver-checks` output from the sandbox for both feature sets, names the baseline version it compared against, and lists the lints it would have fired on if the branch broke something, so a reviewer knows what a failure will look like before one happens.

The run's record keeps every command with its output: the tool installation, the baseline download, both comparisons and the `cargo test` pass, with the exact toolchain version the sandbox used.

Before merging, a reviewer checks that the pull request trigger is the right one for the crate's release process (a crate that bumps the version in the same pull request as the breaking change will see the check pass, which is the intended behaviour), decides whether the docs.rs feature set or `--all-features` is the better second run, and confirms the job name fits any branch protection rules that list required checks.

## Run it on every Linear issue labelled agent

In the console, an automation in the Project that has the repository, with a `linear` trigger on `linear.issue.labeled` and `config.labels` set to `agent`, starts one run per issue, with the issue text added after the prompt. A ticket that says which crates in a workspace need the check, or which feature sets to compare, reaches the agent that way, and the pull request links the issue.

From your own server, the same work is one `POST /o/{org}/sessions` with this body and the repository in `resources`; a webhook on the API key reports `run.completed` with the `session_url` to read the pull request link.

## Why run it on Rush?

Adding a CI job sounds like ten lines of YAML, but the useful version depends on reading the crate: which features change the public types, which feature set the docs are built with, how the existing workflow installs tools and when it skips jobs. An agent that reads `Cargo.toml` and `ci.yml` first produces a job that matches the file it lands in, and one that runs at the right moments instead of failing every release push.

The sandbox has a real Rust toolchain, so the agent runs the comparison before opening the pull request and the output is kept in the run's record. The pull request arrives with evidence of what the check reports today, not a promise that it will work. Several crates in an organisation can be done at once, each in its own sandbox.

## Frequently asked questions

### What is the baseline it compares against?

By default cargo-semver-checks fetches the latest version of the crate published on crates.io and compares the current source against it. For a crate that is not published, the agent switches to a git baseline, the default branch at the merge base, and says so in the pull request.

### Will it fail when I intentionally bump the major version?

No. The tool compares the version in `Cargo.toml` with the baseline's version and only reports a change as a failure when the bump you declared is smaller than the one the change requires. A breaking change in a pull request that also bumps the major version passes.

### Why run it with two feature sets?

Features such as `preserve_order` change public types, so an API only visible under a feature is only checked when that feature is on. The default run covers what every user gets; the second run covers the feature set the docs are built with. `--all-features` is an option if every feature is meant to be stable.

### Does it slow CI down?

The job builds rustdoc JSON for the current crate and the baseline, roughly the cost of two `cargo doc` runs, and runs in parallel with the other jobs. It runs on pull requests only, so pushes to the default branch and the nightly schedule are unaffected.

## More Rust library jobs

- [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/)
- [Add cargo-semver-checks to CI for a Rust Library](https://getrush.ai/run/add-cargo-semver-checks-to-ci/rust-library/)

## More jobs like this: Turn a Linear label into a PR

- [Add Server-Side Pagination to a TanStack Router Page](https://getrush.ai/run/add-server-side-pagination/tanstack-router/)
- [Add Prometheus ServiceMonitors to a Kustomize App](https://getrush.ai/run/add-service-monitors/kustomize/)
- [Add Shell Completion to a Go CLI from a Linear Issue](https://getrush.ai/run/add-shell-completion/go-cli/)

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