@@ -284,12 +284,66 @@ pnpm run benchmark:canary -- --runs 1 --reasoning minimal
284284
285285## Publish a release
286286
287- Publish releases by hand from a clean ` main ` checkout. First update the version
288- and create its commit and tag. Pass ` patch ` , ` minor ` , an exact version, or any
289- other value accepted by ` pnpm version ` :
287+ Use the GitHub Actions ` Release ` workflow for normal releases. Run it from
288+ ` main ` and enter one exact version such as ` 0.11.0 ` or ` 0.11.0-beta.1 ` . The input
289+ must be canonical SemVer: ranges, ` patch ` or ` minor ` aliases, surrounding
290+ whitespace, build metadata, and shell syntax are rejected.
291+
292+ Before the first run, configure the npm package's trusted publisher with this
293+ exact tuple:
294+
295+ - provider: GitHub Actions
296+ - organization or user: ` itsjling `
297+ - repository: ` diffsplain `
298+ - workflow filename: ` release.yml `
299+ - environment: ` npm-publish `
300+ - allowed action: ` npm publish `
301+
302+ Create the protected ` npm-publish ` environment in GitHub. Allow this workflow's
303+ ` GITHUB_TOKEN ` to update ` main ` and release tags under your branch and tag
304+ rules. Configure any required environment reviewers. These npm and GitHub
305+ settings are prerequisites; the repository does not prove that they exist.
306+
307+ The workflow prepares and verifies the release without repository write access
308+ or an npm identity. It passes the tarball, verification receipt, release commit,
309+ and tag to a separate protected job. Only that final job receives GitHub write
310+ access and the npm OIDC identity. It independently checks the artifact, pushes
311+ the exact version commit and tag atomically, and publishes the tarball with
312+ package lifecycle scripts disabled. Stable versions use the ` latest ` npm tag
313+ and prereleases use ` next ` . Releases are serialized so two workflow runs cannot
314+ publish concurrently.
315+
316+ ### Recover a workflow release
317+
318+ Rerun the failed publish job in the existing workflow run, or start a new run
319+ with the same exact version after a failure. The publish-job rerun retains the
320+ original verified artifact and dispatch commit, and is accepted when that
321+ commit is the parent of the pushed release. Rerunning every job from an older
322+ dispatch is rejected after ` main ` advances; start a new workflow run instead.
323+ The workflow accepts only these states:
324+
325+ - ** Create:** ` main ` still contains the previous package version, the requested
326+ tag and npm version do not exist, and local ` main ` matches ` origin/main ` .
327+ - ** Resume:** the requested package version and tag are already on the same
328+ commit at ` origin/main ` , but npm does not contain the version.
329+ - ** Complete:** Git is in the resume state and npm contains the version. The
330+ workflow rebuilds the verified tarball and succeeds only when its SHA-512 SRI
331+ matches npm's ` dist.integrity ` .
332+
333+ A moved branch, conflicting tag, local-only version commit, or mismatched npm
334+ tarball is a mixed state and stops the workflow. Inspect and reconcile Git and
335+ npm before rerunning. If the atomic push failed and left only a local commit and
336+ tag in the runner, start a new run; if reproducing locally, delete or reconcile
337+ those local refs without overwriting remote history.
338+
339+ ### Publish locally as a fallback
340+
341+ Use local publication only when the GitHub workflow cannot be used. Start from
342+ a clean ` main ` checkout, update the version, and create its commit and tag. Pass
343+ the exact intended version to ` pnpm version ` :
290344
291345``` sh
292- corepack pnpm version patch
346+ corepack pnpm version 0.11.0
293347```
294348
295349Do not push yet. Verify the tagged commit and build the release tarball:
@@ -306,12 +360,12 @@ Sign in to npm when needed, then publish by naming the exact version again:
306360
307361``` sh
308362COREPACK_ENABLE_PROJECT_SPEC=0 corepack npm@11.5.1 login --auth-type=web
309- corepack pnpm run release:publish -- 1.0 .0
363+ corepack pnpm run release:publish -- 0.11 .0
310364```
311365
312366The publish command checks the clean tree, tag, commit, tarball hash, npm login,
313- and registry before it publishes. Stable versions use the ` latest ` npm tag;
314- prereleases use ` next ` . Local publication does not add npm provenance.
367+ and registry before it publishes. Local publication does not use the workflow's
368+ trusted-publisher identity or add npm provenance.
315369
316370After npm confirms the version, push the version commit and tag:
317371
0 commit comments