| name | cargo-publish |
| description | Operate the socket-release crates.io flow - the cargo staged model (dry-run default), trusted publishing via OIDC under the cargo-publish environment, index-propagation waits, and yank-as-rollback. Use when publishing a Rust crate in a repo carrying scripts/socket-release/. |
crates.io publish (staged model)
crates.io publishes are PERMANENT (yank-only, no unpublish), so the kit's
cargo flow is dry-run by default everywhere and the real publish runs only
under the cargo-publish GitHub environment through crates.io Trusted
Publishing (OIDC - no long-lived token anywhere).
Bootstrap
The same bootstrap stands up the cargo-publish environment
(branch-restricted) and installs cargo-publish.yml:
node scripts/socket-release/bootstrap.mts github-env staged-config --apply
crates.io's trusted-publisher config (crate ↔ repo ↔ workflow ↔
environment) is set on crates.io's settings page by the crate owner - a
human step; render it as a gate with the crate's settings URL, do not
improvise a browser drive.
Release cycle
-
Bump: Cargo.toml version + CHANGELOG, commit
chore: bump version to <version>, push.
-
Dry-run locally:
node scripts/socket-release/cargo-publish.mts --staged --dry-run
-
Publish from CI: the operator dispatches the cargo publish workflow
from the Actions UI with publish: true (gh workflow run is
guard-blocked for agents - the human clicks). The workflow runs
--direct under the cargo-publish environment with the OIDC-minted
token; a dry-run dispatch runs --staged --dry-run ungated.
-
Index propagation: the publish is not "done" until the version appears
in the crates.io index - the engine's registry gate polls
https://index.crates.io/<path> and the tag/release cut waits for it
(ORDER RULE: the GitHub release follows index resolvability, never
precedes it). Do not retry a publish that is merely propagating.
-
The tag + immutable release cut follows automatically; a gap heals with
node scripts/socket-release/github-release.mts --tag vX.Y.Z --release.
Local emergencies
node scripts/socket-release/cargo-publish.mts --direct publishes from the
operator's machine with their own cargo login token - 2FA/auth is theirs
to provide (gate, never scripted). --approve promotes a staged cargo
entry where the staged lane is available; --package <name> disambiguates
a workspace (multi-crate ordering is deferred - the tool refuses ambiguity
rather than guessing).
Rollback = yank
cargo yank --version X.Y.Z # from the crate root, operator auth
cargo yank --version X.Y.Z --undo
Yank never deletes bytes - existing lockfiles keep resolving; new
resolutions skip the version. Ship the fixed version immediately after, and
deprecate nothing (crates.io has no deprecate).
