po4yka/rust-skills / skills/rust-crate-release
rust-crate-release
VerifiedUse when preparing to publish a Rust crate or a Rust binary release, or recovering from a bad one - deciding a SemVer bump or MSRV change, checking cargo package and cargo publish output, ordering a workspace publish, setting up crates.io trusted publishing, deciding whether to yank a crate version, building a release archive with a release checksum, release SBOM, and attestation, or using cosign to sign release artifacts.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.5 KB |
| references/binary-distribution.md | markdown | 15.3 KB |
| references/compatibility.md | markdown | 6.6 KB |
| references/package-inspection.md | markdown | 2.4 KB |
| references/recovery.md | markdown | 2.5 KB |
| references/release-inputs-and-metadata.md | markdown | 2.5 KB |
| references/trusted-publishing.md | markdown | 6.3 KB |
| references/workspace-publish.md | markdown | 1.5 KB |
references/trusted-publishing.md
View on GitHub# crates.io Trusted Publishing
Read this when a CI workflow publishes a crate to crates.io, or when you change the crate's
publisher settings. Facts are as of 2026-09; the source links are at the end.
Contents: What it changes, Configure the publisher, Workflow, Token fallback, Verify before the
tag push, Sources.
## What it changes
- The CI job exchanges its OIDC identity for a crates.io token. The token expires after 30
minutes, and the post step of `rust-lang/crates-io-auth-action` revokes it when the job ends.
No long-lived registry secret exists in the repository.
- GitHub Actions is supported. GitLab.com CI/CD is in public beta. Self-hosted GitLab is not
supported.
- The first publish of a new crate needs an API token. Configure the trusted publisher after it.
- crates.io rejects workflows that the `pull_request_target` or `workflow_run` trigger starts.
- An owner can enable "Trusted Publishing only" in the crate settings. That setting disables
API-token publishing for the crate.
## Configure the publisher
The crates.io crate settings take the repository owner, the repository name, the workflow file
name (for example `release.yml`), and an optional environment. On GitLab.com they take the
namespace, the project, the workflow file path, and an optional environment.
A settings change is an owner-level external write. Get authorization for the exact values.
Enable "Trusted Publishing only" only after the workflow has published one version, and get
authorization for that change too.
## Workflow
Pin every action to a full commit SHA with a version comment. The `cargo-workflows` skill, when it
is installed, owns the pinning rule.
```yaml
name: Publish to crates.io
on:
push:
tags: ['v*']
jobs:
publish:
runs-on: ubuntu-latest
environment: release
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Check that the tag matches the package version
run: |
version="$(cargo metadata --locked --format-version 1 --no-deps \
| jq -r '.packages[] | select(.name == "<package>") | .version')"
if [ "${GITHUB_REF_NAME#v}" != "$version" ]; then
echo "tag $GITHUB_REF_NAME does not match <package> $version" >&2
exit 1
fi
- uses: rust-lang/crates-io-auth-action@c6f97d42243bad5fab37ca0427f495c86d5b1a18 # v1.0.5
id: auth
- run: cargo publish --locked -p <package>
env:
CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
```
- Give `id-token: write` only to the publish job.
- Add required reviewers to the `release` environment, and enter the same environment name in the
crate settings. The environment then gates each publish.
- Start the job from a tag push or a manual dispatch. Limit the tag pattern to release tags. Run a
manual dispatch on the tag ref: the version check fails on a branch name.
- Set `persist-credentials: false` on the checkout. Otherwise the checkout leaves the `GITHUB_TOKEN`
in the git configuration, where a build script that `cargo publish` verifies can read it.
- Do not restore or save a shared build cache in the publish job. A job that can write a cache
that pull requests read must not hold secrets.
- Run the release gates in an earlier job. The publish job runs `cargo publish` without
`--allow-dirty` and without `--no-verify`.
## Token fallback
Use a stored token only when Trusted Publishing is not available: another registry, another CI
host, or the first publish. Store the token as a CI secret. Never echo it.
For crates.io, create a token with the `publish-update` scope (add `publish-new` only for a first
publish) and a crate-name pattern. crates.io tokens expire after 90 days by default, so an old CI
secret can start to fail authentication. Pass the token as `CARGO_REGISTRY_TOKEN`.
For another registry, pass the token as `CARGO_REGISTRIES_<NAME>_TOKEN` (the registry name in
upper case, with `-` as `_`), or use the credential provider that the registry documents.
`CARGO_REGISTRY_TOKEN` is the crates.io token only. Follow the token policy of that registry.
## Verify before the tag push
| Check | Evidence |
|---|---|
| Trigger | `on:` names a tag push or `workflow_dispatch`, not `pull_request_target` or `workflow_run` |
| Permissions | `id-token: write` on the publish job only |
| Pins | Every `uses:` has a 40-character SHA and a version comment |
| Environment | The job environment matches the crate settings and has required reviewers |
| Publisher | The crate settings list this repository, this workflow file, and this environment |
| Command | `cargo publish --locked -p <package>`, with no `--allow-dirty` or `--no-verify` |
| Version | The checkout has `persist-credentials: false`, and a step fails when the tag differs from the package version |
After the job, read its log, then confirm the version with
`cargo info <package>@<version> --registry crates-io`.
| Failure | Likely cause | Fix |
|---|---|---|
| Auth step fails on a new crate | The crate has no published version | Do the first publish with a scoped token |
| Auth step fails on an existing crate | Workflow file, repository, or environment differs from the settings | Correct the settings or the workflow; do not add a token secret as a workaround |
| Auth step fails with an OIDC error | `id-token: write` is missing | Add it to the publish job |
| Publishing fails only for some runs | `pull_request_target` or `workflow_run` started those runs | Use a tag push or a manual dispatch |
## Sources
- [crates.io Trusted Publishing](https://crates.io/docs/trusted-publishing)
- [crates-io-auth-action](https://github.com/rust-lang/crates-io-auth-action)
- [crates.io development update, 2026-01](https://blog.rust-lang.org/2026/01/21/crates-io-development-update/)
- [crates.io development update, 2025-02](https://blog.rust-lang.org/2025/02/05/crates-io-development-update/)
- [crates.io token scopes, RFC 2947](https://rust-lang.github.io/rfcs/2947-crates-io-token-scopes.html)
- [Cargo registry tokens in config](https://doc.rust-lang.org/cargo/reference/config.html#registriesnametoken)
- [GitHub Actions cache and secrets advisory](https://blog.rust-lang.org/2026/09/21/github-actions-leaking-secrets-when-miri-output-is-cached/)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |