putitoutthere 0.2.10 → 0.2.11

package/CHANGELOG.md

@@ -12,6 +12,7 @@ are prefixed `**BREAKING**` and link to the matching section in
 
 ### Added
 
+- **Reusable workflow accepts a caller-provided `CARGO_REGISTRY_TOKEN` via `secrets:`.** OIDC trusted publishers remain the default and recommended path, but Trusted Publishing on crates.io binds to an *already-published* crate — so the first publish of a brand-new crate has no OIDC path available, and consumers were forced to either fork the workflow or run `cargo publish` outside it. The `workflow_call` surface now declares an optional `CARGO_REGISTRY_TOKEN` secret; when set, the `rust-lang/crates-io-auth-action` OIDC exchange is skipped and the caller-provided token is exported to `$GITHUB_ENV` for the engine's crates handler to read. Callers without a token keep the OIDC path unchanged. The "Auth: OIDC trusted publishers ... Long-lived registry tokens are explicitly NOT supported" framing in `release.yml`'s header has been softened to match. See [README → Trusted publishers → crates.io](./README.md#cratesio) and [MIGRATIONS.md](./MIGRATIONS.md#crates-token-fallback). #283.
 - **Preflight check: every cascaded `kind = "npm"` package must declare a non-empty `repository` field in `package.json`.** `putitoutthere` invokes `npm publish --provenance` on the OIDC trusted-publisher path, and the npm CLI hard-requires this field so the registry can verify the artifact was built from the repo the trusted publisher declares. A missing or empty field previously surfaced as a confusing tail-end npm error after the runner had spun up, OIDC had been negotiated, and the artifact had been built — wasting a full release run on a precondition checkable in milliseconds. The new `requireProvenanceMetadata` runs alongside `requireAuth` in `src/publish.ts`, before any side effects, and reports every failing package in one error rather than failing on the first. Surfaces a new stable error code, `PIOT_NPM_MISSING_REPOSITORY`. Both the canonical object form (`{ type, url, directory? }`) and the legacy single-string form are accepted; only an empty `url` (or no `url` at all) fails. The npm handler's inline backstop is also tightened to match the same predicate (previously `!pkg.repository` slipped `{}`, `{ type: 'git' }`, and whitespace strings through). Documented in [README → `kind = "npm"`](./README.md#kind--npm). See [MIGRATIONS.md](./MIGRATIONS.md#npm-package-json-must-declare-repository). #280.
 - **Reusable workflow `.github/workflows/build.yml` (`workflow_call`).** PR-time build verification: runs the same plan + build matrix that `release.yml` runs, calling a shared internal `_matrix.yml` reusable workflow so action pins, per-target build steps, and runner selection cannot drift between the two paths. `build.yml` declares only `permissions: contents: read` and contains no publish job, no `id-token: write`, no OIDC trusted-publisher exchange, and no registry auth — the bytes required to publish do not exist on this code path. Two optional inputs forwarded to `_matrix.yml`: `node_version` (default `24`), `python_version` (default `3.12`). Concurrency is keyed on `github.ref` with `cancel-in-progress: true` so PR pushes supersede stale runs (release.yml's repository-keyed group with `cancel-in-progress: false` is unchanged). An `actionlint`-job grep assertion rejects any future patch that adds `id-token: write` to `build.yml` or `_matrix.yml`. See [README → Build check](./README.md#1b-optional-drop-in-githubworkflowsbuild-checkyml) and [MIGRATIONS.md](./MIGRATIONS.md#new-buildyml-reusable-workflow-for-pr-time-build-verification).
 - **`PIOT_PUBLISH_EMPTY_PLAN` error code.** Surfaced when `publish` is invoked with an empty matrix. Joins `PIOT_AUTH_NO_TOKEN` in the stable error-code vocabulary; foreign agents debugging a failed publish can fingerprint on the code without parsing prose.

package/MIGRATIONS.md

@@ -21,6 +21,66 @@ Each section covers five things, in order:
 
 ## Unreleased
 
+### Crates token fallback
+
+**Summary.** The reusable workflow now accepts an optional
+`CARGO_REGISTRY_TOKEN` via `secrets:`. Trusted Publishing on
+crates.io binds to an *already-published* crate, so the very
+first publish of a brand-new crate has no OIDC path available;
+without this fallback consumers had to either fork the workflow
+or publish once outside it. OIDC trusted publishers remain the
+default and recommended path — when the secret is unset,
+behavior is byte-for-byte unchanged. When the secret is set,
+the `rust-lang/crates-io-auth-action` OIDC exchange is skipped
+and the caller-provided token is exported to `$GITHUB_ENV` as
+`CARGO_REGISTRY_TOKEN` for the engine's crates handler to read.
+The header comment in `.github/workflows/release.yml` has been
+softened to match: previously *"Long-lived registry tokens are
+explicitly NOT supported via this workflow"*; now OIDC is
+described as the default with the token fallback called out for
+first-publish bootstrap. #283.
+
+**Required changes.** None for consumers already on the OIDC
+path. To bootstrap a brand-new crate or to use the workflow on
+an account where Trusted Publishing isn't available, wire the
+secret in the caller's `release.yml`:
+
+| Before                                                                                 | After                                                                                                                                                                                |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0`                   | `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0`<br>`secrets:`<br>`  CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}`                                   |
+
+The repo-level secret holding the crates.io API token can be
+named anything; the *workflow* secret it gets passed as must
+be `CARGO_REGISTRY_TOKEN` exactly — the reusable workflow keys
+on that name. Drop the `secrets:` block from the caller's
+`release.yml` once Trusted Publishing is registered against
+the now-existing crate; subsequent publishes are zero-secret.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** None when the secret
+is unset (OIDC path unchanged). When the secret is set, the
+publish job's "Authenticate with crates.io (OIDC)" step is
+conditionally skipped and a new "Export CARGO_REGISTRY_TOKEN
+(caller-provided)" step writes the secret to `$GITHUB_ENV`
+gated on the same condition. The gate reads the secret through a
+job-level `CALLER_CARGO_REGISTRY_TOKEN` env var because GitHub
+Actions does not allow the `secrets` context inside step-level
+`if:` conditions ([context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability));
+this is an internal mechanism — consumers don't see or set
+`CALLER_CARGO_REGISTRY_TOKEN` themselves.
+
+**Verification.** Wire `CARGO_REGISTRY_TOKEN` to a valid
+crates.io API token in the caller repo and trigger a release.
+The publish-job logs should show "Authenticate with crates.io
+(OIDC)" as `skipped`, "Export CARGO_REGISTRY_TOKEN (OIDC)" as
+`skipped`, and "Export CARGO_REGISTRY_TOKEN (caller-provided)"
+as `success`. The crate publishes; the only difference visible
+in the registry is the publish was authorised against the
+caller-provided token rather than an OIDC-minted ephemeral one.
+
+---
+
 ### npm package.json must declare `repository`
 
 **Summary.** Every cascaded `kind = "npm"` package's `package.json`

package/README.md

@@ -301,23 +301,48 @@ releases without fighting registry-immutable-publish semantics.
 
 ## Trusted publishers
 
-OIDC trusted publishers — the only auth path supported. Long-lived
-registry tokens are not reachable through the workflow.
-
-For all three registries the fields are the same: **your** repository
-owner/name, **your** workflow filename (`release.yml`), and optionally
-a GitHub environment name. Note: you register against your *own*
-repository, not against `thekevinscott/putitoutthere` — see "How
-auth flows" below for the why.
+OIDC trusted publishers are the default and recommended auth path.
+The reusable workflow also accepts a long-lived `CARGO_REGISTRY_TOKEN`
+via `secrets:` for cases where Trusted Publishing isn't reachable —
+most commonly the very first publish of a brand-new crate, since
+Trusted Publishing on crates.io binds to an *already-published* crate
+and there's no pending-publisher equivalent. When set, the OIDC
+exchange is skipped and the caller-provided token is used instead.
+Drop the secret once Trusted Publishing is registered against the
+existing crate.
+
+For all three registries the OIDC fields are the same: **your**
+repository owner/name, **your** workflow filename (`release.yml`),
+and optionally a GitHub environment name. Note: you register against
+your *own* repository, not against `thekevinscott/putitoutthere` —
+see "How auth flows" below for the why.
 
 ### crates.io
 
-1. Publish your crate once through the normal `cargo` flow so the crate
-   exists. (Trusted publishing needs a crate owner record.)
+1. **First publish (brand-new crate).** Trusted Publishing binds to
+   an existing crate, so the first `cargo publish` has no OIDC path.
+   Either run `cargo publish` once locally with your account's API
+   token, or pass `CARGO_REGISTRY_TOKEN` to the reusable workflow via
+   `secrets:` to bootstrap through this workflow:
+
+   ```yaml
+   jobs:
+     release:
+       uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0
+       secrets:
+         CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+   ```
+
+   When `CARGO_REGISTRY_TOKEN` is set, the OIDC step
+   (`rust-lang/crates-io-auth-action`) is skipped and the caller-
+   provided token is exported to the publish step's environment.
 2. Go to `https://crates.io/crates/<crate>/settings` → **Trusted Publishing**
    → **Add**.
 3. Fill in: your repo owner, your repo name, workflow filename
    (`release.yml`), environment (optional).
+4. Drop the `CARGO_REGISTRY_TOKEN` secret from the workflow once
+   Trusted Publishing is registered; subsequent publishes are
+   zero-secret on the OIDC path.
 
 ### PyPI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "putitoutthere",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Polyglot release orchestrator for crates.io, PyPI, and npm",
   "license": "MIT",
   "repository": {