Skip to content

Commit 74304ce

Browse files
authored
release: stage npm versions instead of publishing them (#6622)
* release: stage npm versions instead of publishing them CI runs `npm stage publish` for zod and @zod/mini. Both trusted publishers are stage-only, so the workflow can reserve a version in npm's staged queue and nothing more; a maintainer approves each one with 2FA before the registry serves it. Both packages stage back to back so one approval session covers the pair, and the two registry-liveness waits collapse into a single wait with a 350-minute deadline under the job's existing 360-minute cap. The wait writes a step summary naming the staged versions and the approval commands, and it still absorbs the automated review npm runs after an approval. `continue-on-error` comes off both steps: staging has to fail loudly now that it is not masking a publish conflict. A version already served is skipped and a version already staged is tolerated, so re-running the job after a late approval works. * release: dispatch-only trigger, and refuse a ref other than main
1 parent 34a626f commit 74304ce

2 files changed

Lines changed: 103 additions & 51 deletions

File tree

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
#!/usr/bin/env bash
2+
# Stage one package directory on npm: `npm stage publish` through OIDC trusted publishing.
3+
#
4+
# CI can only STAGE. The trusted publisher on zod and on @zod/mini is stage-only, so a version
5+
# reaches the registry only once a maintainer approves it with 2FA — a proof of presence that no
6+
# token, and no stolen push credential, can supply.
7+
#
8+
# Idempotent, because the job it runs in is re-run after a late approval: a version the registry
9+
# already serves is skipped, and a version already sitting in the staged queue makes `npm stage
10+
# publish` refuse, which counts as success here — the approval wait downstream is what decides
11+
# whether the version arrived. That refusal's exact wording is matched loosely, since the first
12+
# stage-only release is where it gets observed; anything else is fatal.
13+
set -euo pipefail
14+
15+
dir="${1:?usage: npm-stage-publish.sh <package-dir> [npm stage publish flags...]}"
16+
shift
17+
version="${VERSION:?VERSION must name the version being staged}"
18+
19+
name="$(nub --node -p "require('./$dir/package.json').name")"
20+
# registry.npmjs.org wants the scope separator percent-encoded: @zod/mini -> @zod%2fmini.
21+
encoded="${name/\//%2f}"
22+
23+
if curl -sf "https://registry.npmjs.org/$encoded/$version" > /dev/null; then
24+
echo "$name@$version is already on the registry"
25+
exit 0
26+
fi
27+
28+
echo "staging $name@$version"
29+
out="$(mktemp)"
30+
trap 'rm -f "$out"' EXIT
31+
if (cd "$dir" && npm stage publish "$@") > "$out" 2>&1; then
32+
cat "$out"
33+
exit 0
34+
fi
35+
cat "$out"
36+
if grep -qiE 'already (been )?staged|staged version|E409|EPUBLISHCONFLICT|previously published' "$out"; then
37+
echo "$name@$version is already staged; the approval wait decides the rest"
38+
exit 0
39+
fi
40+
echo "::error::staging $name@$version failed"
41+
exit 1

‎.github/workflows/release.yml‎

Lines changed: 62 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
name: Release on npm
44
on:
5-
# a version bump on main publishes nothing by itself; a maintainer runs `gh workflow run release.yml` and approves the npm environment
5+
# Dispatch only, and deliberately so. A `workflow_dispatch` needs a GitHub session or token carrying write access; a stolen git push credential carries neither, so it can no longer start a release by landing a commit or cutting a tag. That is the shape of the 2026-09-21 nubjs/nub compromise, where a stolen push credential cut a tag and 18 packages published unattended. A version bump on main is therefore inert: a maintainer runs `gh workflow run release.yml`, approves the npm environment, and then approves each staged version on npm with 2FA.
66
workflow_dispatch:
77

88
jobs:
@@ -19,6 +19,11 @@ jobs:
1919
typescript: ["5.5", "6"]
2020
name: Test with TypeScript ${{ matrix.typescript }} on Node ${{ matrix.node }} (${{ matrix.os }})
2121
steps:
22+
# A step, not a job-level `if:`: a skipped job is silent, and the run would go green having released nothing while looking like it had. This job gates the publish, so failing here stops the release.
23+
- name: Refuse to release from any ref but main
24+
run: |
25+
[ "$GITHUB_REF" = "refs/heads/main" ] || { echo "::error::release.yml runs from main only, got $GITHUB_REF"; exit 1; }
26+
2227
- uses: actions/checkout@v7
2328
- run: printf '%s\n' "${{ matrix.node }}" > .nvmrc
2429
- uses: nubjs/setup-nub@47e5e7393d50f4e9544ddaf756aa277972afba2d # v0
@@ -67,9 +72,9 @@ jobs:
6772
build_and_publish:
6873
needs: [test-node, lint, check-circular]
6974
runs-on: ubuntu-latest
70-
# a required reviewer approves every publish, and the environment only deploys main; npm's trusted publishers are bound to it so no other branch or workflow can publish
75+
# a required reviewer approves every run, and the environment only deploys main; npm's trusted publishers are bound to it so no other branch or workflow can even stage. The environment is the first of two gates — the second is the 2FA approval of each staged version, which this job cannot perform.
7176
environment: npm
72-
# 6h is GitHub's hard cap for a hosted runner, not a tunable. The two npm waits below share it, so neither can have the whole thing: zod gets 240 minutes because it is the one that waits on review, and @zod/mini gets 90 because it publishes after that review has already drained (it cleared in under a minute on 4.6.0). A stall that outlives the pair needs the wait moved to its own job rather than a larger number here, and that costs a second environment approval.
77+
# 6h is GitHub's hard cap for a hosted runner, not a tunable. One wait now covers both packages: they are staged back to back, so a single approval session releases the pair and the maintainer is never asked to be present twice. The wait takes 350 of the 360 minutes. A stall that outlives it needs the wait moved to its own job rather than a larger number here, and that costs a second environment approval.
7378
timeout-minutes: 360
7479
permissions:
7580
contents: write
@@ -85,6 +90,19 @@ jobs:
8590
with:
8691
nub-version: "0.8.3"
8792
registry-url: https://registry.npmjs.org/
93+
94+
# `npm stage publish` landed in npm 11.15, later than the npm bundled with any Node the
95+
# action provisions. setup-nub fronts that Node's bin dir on PATH, so the global install
96+
# lands in the same prefix the `npm` below resolves from — the echo proves which one.
97+
- name: Install an npm CLI that can stage
98+
run: | # zizmor: ignore[adhoc-packages] the npm CLI itself, pinned to the major that carries `npm stage`
99+
npm install -g npm@11
100+
v="$(npm --version)"
101+
# `sort -V | head -1` yields the smaller of the two; it has to be the floor.
102+
[ "$(printf '%s\n11.15.0\n' "$v" | sort -V | head -1)" = "11.15.0" ] \
103+
|| { echo "::error::npm $v cannot stage (need >= 11.15)"; exit 1; }
104+
echo "npm $v at $(command -v npm)"
105+
88106
- run: nub install --frozen-lockfile
89107
- run: nub run build
90108
- run: nub run test
@@ -101,32 +119,51 @@ jobs:
101119
echo "zod=$(nub --node -p "require('./packages/zod/package.json').version")" >> "$GITHUB_OUTPUT"
102120
echo "mini=$(nub --node -p "require('./packages/mini/package.json').version")" >> "$GITHUB_OUTPUT"
103121
104-
- id: publish
105-
name: Publish to NPM
106-
# npm may stage a version before reporting a conflict; registry liveness is the final gate
107-
continue-on-error: true
108-
working-directory: ./packages/zod
122+
# This job cannot publish. Both trusted publishers are stage-only, so all it can do is put a version in npm's staged queue, where it is not installable and its number is reserved; a maintainer then approves it with 2FA. A credential that reaches this workflow can therefore fill a queue and nothing else.
123+
- name: Stage zod on npm
109124
env:
110125
VERSION: ${{ steps.version.outputs.zod }}
111-
run: |
112-
if curl -sf "https://registry.npmjs.org/zod/$VERSION" > /dev/null; then exit 0; fi
113-
nub publish --provenance --no-git-checks
126+
run: bash .github/scripts/npm-stage-publish.sh packages/zod --provenance
114127

115-
# npm holds a publish in automated review before serving it, and the version is unavailable until that finishes: 4.5.0 sat 16 minutes, 4.5.3 sat 25, and 4.6.0 sat 116. None of those is an upper bound. The version does arrive, and the release and the JSR publish are worthless without it, so wait rather than fail. A publish that failed for some other reason waits the whole window and then fails with the publish step's log to read.
116-
- name: Wait for the version to be live on npm
128+
# @zod/mini ships in lockstep with zod and is a no-op when its version is already on the registry, so it runs unconditionally (the first release of the scoped package rides on a merge that does not bump zod itself). It is staged here, next to zod and before the wait, so both versions are in the queue when the maintainer sits down: one approval session covers the pair, and `pnpm stage approve` takes them under a single one-time password. Under the old irreversible publish this step ran last, so that a failed @zod/mini publish could not cost zod its tag; staging removes that hazard, because a failure here leaves zod staged and unapproved rather than live and unmatched.
129+
- name: Stage @zod/mini on npm
117130
env:
118-
VERSION: ${{ steps.version.outputs.zod }}
131+
VERSION: ${{ steps.version.outputs.mini }}
132+
run: bash .github/scripts/npm-stage-publish.sh packages/mini --provenance --access public
133+
134+
# THE HUMAN GATE. Both versions sit in the staged queue until a maintainer approves them, and the registry serves them only after that, so everything below — the tag, the GitHub release, both JSR publishes — is downstream of the approval and nothing public ever describes a version npm did not ship. The loop also absorbs the automated review npm runs once a version is approved, which held 4.5.0 for 16 minutes, 4.5.3 for 25 and 4.6.0 for 116; none of those is an upper bound. A GitHub job gets six hours at most. If the approval comes later, re-run this job: a live version is skipped, a staged one is tolerated, and the wait then passes at once.
135+
- name: Wait for the staged versions to be approved and live
136+
env:
137+
ZOD_VERSION: ${{ steps.version.outputs.zod }}
138+
MINI_VERSION: ${{ steps.version.outputs.mini }}
119139
run: |
120-
for i in $(seq 1 240); do
121-
if curl -sf "https://registry.npmjs.org/zod/$VERSION" > /dev/null; then
122-
echo "zod@$VERSION is live"
123-
exit 0
124-
fi
125-
if [ $((i % 15)) -eq 0 ]; then echo "zod@$VERSION is not on the registry yet ($i minutes)"; fi
126-
sleep 60
127-
done
128-
echo "zod@$VERSION never reached the registry; see the publish step for why"
129-
exit 1
140+
# shellcheck disable=SC2016 # the backticks below are markdown for the step summary, not command substitution
141+
{
142+
echo "## Staged on npm, waiting for approval"
143+
echo
144+
echo "- \`zod@$ZOD_VERSION\`"
145+
echo "- \`@zod/mini@$MINI_VERSION\`"
146+
echo
147+
echo 'Neither version is installable until you approve it with 2FA. Read the stage ids with `npm stage list zod` and `npm stage list @zod/mini`, then approve each with `npm stage approve <id>`; `pnpm stage approve` takes both in one interactive picker under a single one-time password, as does the Staged Packages tab on npmjs.com.'
148+
echo
149+
echo 'This job waits 350 minutes. If it runs out, approve the versions and re-run it.'
150+
} >> "$GITHUB_STEP_SUMMARY"
151+
deadline=$(( $(date +%s) + 350 * 60 ))
152+
wait_for () {
153+
local label="$1" url="$2" i=0
154+
until curl -sf "$url" > /dev/null; do
155+
if [ "$(date +%s)" -ge "$deadline" ]; then
156+
echo "::error::$label is still not on the registry; approve the staged version with 2FA, then re-run this job"
157+
exit 1
158+
fi
159+
i=$((i + 1))
160+
if [ $((i % 15)) -eq 0 ]; then echo "$label is still staged, awaiting approval ($i minutes)"; fi
161+
sleep 60
162+
done
163+
echo "$label is live"
164+
}
165+
wait_for "zod@$ZOD_VERSION" "https://registry.npmjs.org/zod/$ZOD_VERSION"
166+
wait_for "@zod/mini@$MINI_VERSION" "https://registry.npmjs.org/@zod%2fmini/$MINI_VERSION"
130167
131168
- name: Configure changelog
132169
run: |
@@ -175,32 +212,6 @@ jobs:
175212
fi
176213
nub exec --node jsr publish --allow-slow-types # --dry-run
177214
178-
# @zod/mini ships in lockstep with zod and is a no-op when its version is already on the registry, so it runs unconditionally (the first release of the scoped package rides on a merge that does not bump zod itself) and last, so a failed mini publish cannot cost zod its tag, GitHub release or JSR publish
179-
- id: publish_mini
180-
name: Publish @zod/mini to NPM
181-
continue-on-error: true
182-
working-directory: ./packages/mini
183-
env:
184-
VERSION: ${{ steps.version.outputs.mini }}
185-
run: |
186-
if curl -sf "https://registry.npmjs.org/@zod%2fmini/$VERSION" > /dev/null; then exit 0; fi
187-
nub publish --provenance --no-git-checks --access public
188-
189-
- name: Wait for @zod/mini to be live on npm
190-
env:
191-
VERSION: ${{ steps.version.outputs.mini }}
192-
run: |
193-
for i in $(seq 1 90); do
194-
if curl -sf "https://registry.npmjs.org/@zod%2fmini/$VERSION" > /dev/null; then
195-
echo "@zod/mini@$VERSION is live"
196-
exit 0
197-
fi
198-
if [ $((i % 15)) -eq 0 ]; then echo "@zod/mini@$VERSION is not on the registry yet ($i minutes)"; fi
199-
sleep 60
200-
done
201-
echo "@zod/mini@$VERSION never reached the registry; see the publish step for why"
202-
exit 1
203-
204215
# JSR refuses a version that already exists, so the step checks first; this also lets the first JSR publish of a version already on npm ride on a merge that publishes nothing to npm
205216
- name: Publish @zod/mini to JSR
206217
working-directory: ./packages/mini
@@ -212,5 +223,5 @@ jobs:
212223
nub exec --node jsr publish --allow-slow-types
213224
fi
214225
215-
# every zod release from 4.5.0 on must have an @zod/mini twin on npm, whichever of the two publishes above ran
226+
# every zod release from 4.5.0 on must have an @zod/mini twin on npm, whichever of the two stagings above ran
216227
- run: nub run check:lockstep --wait

0 commit comments

Comments
 (0)