Skip to content

docs: document the new-crate token bootstrap for trusted publishing #266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GeiserX merged 1 commit into from
Jun 15, 2026
Merged

docs: document the new-crate token bootstrap for trusted publishing #266

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,31 @@ publisher with:
Until a crate has its trusted publisher configured, `release.yml`'s publish step fails *for that
crate only*; the version-bump + tag + GitHub-Release half (release-please.yml) works regardless.

### Adding a NEW `geiserx_*` crate (token bootstrap REQUIRED)

A brand-new crate cannot be created by OIDC trusted publishing — crates.io rejects it with
`403 Forbidden: Trusted Publishing tokens do not support creating new crates. Publish the crate
manually, first`. So the **first** version of any new crate needs a one-time token bootstrap, in
addition to the usual checklist. When you add a new `ts_*` crate, do ALL of:

1. Add it to the workspace `members` + `[workspace.dependencies]` (with `version = "X.Y.Z"
# x-release-please-version`).
2. **Add it to `scripts/publish-crates.sh`'s `CRATES=(…)` array in leaf-first order**, BEFORE any
crate that depends on it (omitting it breaks the whole publish at the first dependent — e.g.
`ts_netmon` missing broke `ts_runtime`'s publish), and bump the `43`→`N` count strings in both
`scripts/publish-crates.sh` and `.github/workflows/release.yml` (incl. the job name).
3. **Token bootstrap (one-time, needs a crates.io token):**
```sh
export CARGO_REGISTRY_TOKEN=<a crates.io API token with "publish" scope>
cargo publish -p geiserx_<new_crate> # creates the crate + its first version
./scripts/setup-trusted-publishing.sh # registers GeiserX/tailscale-rs as its trusted publisher (idempotent; derives the list from cargo metadata, so it picks up the new crate)
```
After that, CI's OIDC trusted publishing handles the crate on every future release.
4. If a release already published the rest of the workspace but failed at the new crate, finish it:
bootstrap the crate (step 3), then re-dispatch the `Release` workflow for the same tag
(`gh workflow run Release --ref main`; `SKIP_PUBLISHED=1` resumes past the already-published
versions).

> **Bulk option (recommended over 43 web forms):** `scripts/setup-trusted-publishing.sh` registers
> the trusted publisher on every publishable crate in one pass via the crates.io API. It is
> idempotent (skips crates already configured) and derives the crate list from `cargo metadata`, so
Expand Down