Automate prerelease publishing with release branches, as drei does

[DennisSmolek]

Publishing 10.0.0-alpha.3 took four failed attempts and about an hour, none of it caused by the code being wrong. The manual path is the problem, and patching it is not the fix — v10 has beta and stable still to come, on a September deadline.

What actually happened

1. pnpm release failed — expired npm token.
2. Re-authed. Failed again — the token had no write access to @react-three/* yet.
3. Access was granted. Failed again — npm's authz cache had not propagated, and it reports that as a 404 on PUT, which reads identically to "you do not have permission". Three of us concluded the wrong thing from it.
4. Eventually worked, publishing the three packages by hand.

The debug log shows 2FA completing cleanly and the PUT failing after it, so the browser challenge was never the issue:

40 http fetch GET 200 .../done?authId=***      ← 2FA completed
41 verbose web auth done-check finished
42 http fetch PUT 404 .../@react-three%2ffiber ← rejected here

None of this is reproducible or reviewable. The alphas so far were published from two different people's laptops (krispyaa for alpha.0–2, dennissmolek for alpha.3), with no provenance attestation on any of them.

Meanwhile, the canary job just works

canary.yml has published cleanly on every push to v10 — via GitHub OIDC, no personal token, with provenance:

10.0.0-canary.611635d   by GitHub Actions   provenance: YES
10.0.0-alpha.2          by krispyaa         provenance: none

So the mechanism is already proven in this repo. It is simply not wired to anything but canary.

What drei does

pmndrs/drei has alpha, beta and rc branches, and one release.yml:

on:
  push:
    branches: ['master', 'beta', 'alpha', 'canary-*', 'rc']

jobs:
  build-and-release:
    needs: test          # release cannot run unless tests pass
    permissions:
      id-token: write    # provenance

with release.config.js mapping branch → dist-tag:

branches: [
  'master',
  { name: 'alpha', prerelease: true },
  { name: 'beta', prerelease: true },
  { name: 'rc', prerelease: true },
  { name: 'canary-*', prerelease: true, channel: 'canary' },
]

Push to alpha → published under the alpha tag. No tokens, no OTP, no laptop, and needs: test makes it impossible to publish something that did not pass CI.

Proposed

Adopt the same shape. The pieces already exist here:

• Trigger: extend a release workflow to alpha / beta / rc branches, modelled on canary.yml, which already has the OIDC trust working.
• Gate: needs: test, so a publish cannot outrun CI. Worth noting test: stop shadowing React's act with a frame-wait helper #3823 and fix: keep interaction state continuous across instance reconstruction #3824 both merged a commit short of what CI had verified — a release gated on a post-merge run would have caught that.
• Tag derivation: scripts/release.js already derives the dist-tag from the version and refuses to touch latest without --allow-latest. Either keep it as the publish step or replace it with semantic-release; the guard rails matter more than the tool.

Open question worth deciding early: semantic-release or the existing script. semantic-release also handles version bumping and changelog generation from commits, which is a larger change to how this repo works. The smaller step is branch-triggered publishing with the current script, keeping hand-written changelogs.

Also worth fixing regardless

scripts/release.js spawns pnpm publish through execFileSync with stdio: 'inherit'. npm's 2FA browser prompt printed but did not appear to block, and publishing by hand is what eventually worked. If any manual path survives, that spawn should hand the TTY through properly — but automating the publish removes the interactive prompt entirely, which is the better answer.

Acceptance

Pushing to a release branch publishes every package under the matching dist-tag, from CI, with provenance, and only after tests pass.

[DennisSmolek]

Implementation

The pieces all exist — canary.yml already publishes via OIDC with provenance, and scripts/release.js already derives the dist-tag. This is mostly rewiring, not new machinery.

1. Branch model

Create long-lived release branches, cut from v10 (and later from master):

alpha   -> publishes @alpha
beta    -> publishes @beta
rc      -> publishes @rc

Version lives in the package.json files, as today. scripts/release.js reads it and derives the tag, so alpha publishing 10.0.0-beta.1 would still correctly go out as beta — the branch is the trigger, not the source of truth. That mismatch should be surfaced rather than silently allowed (see step 4).

2. .github/workflows/release.yml

Modelled directly on the existing canary.yml, which is known-good:

name: Release

on:
  push:
    branches: ['alpha', 'beta', 'rc']
  workflow_dispatch:

permissions:
  id-token: write # npm OIDC -> provenance
  contents: read

jobs:
  release:
    name: Publish prerelease
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: pnpm/action-setup@v4
        with: { run_install: false }
      - uses: actions/setup-node@v5
        with:
          node-version: 24
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      # The full gate. A publish must not be able to outrun CI -- #3823 and #3824
      # both merged a commit short of what their PR checks had verified.
      - run: pnpm run ci

      # `pnpm run ci` ends in `pnpm dev`, which re-stubs dist/. Rebuild, then verify,
      # in that order -- otherwise verify-bundles inspects stubs.
      - run: pnpm build
      - run: pnpm verify-bundles
      - run: pnpm verify-types

      - run: node scripts/release.js
        env:
          NODE_AUTH_TOKEN: ''

Two things worth keeping from canary.yml: --provenance (add it to scripts/release.js's publish args) and NODE_AUTH_TOKEN: '', which is what makes npm use the OIDC identity rather than looking for a token.

3. Gate on CI, not on a separate job

drei uses needs: test against a matrix job. Here the equivalent is running pnpm run ci inline, since our gate is one command. Either shape is fine — the requirement is that no publish step can run unless the gate passed on that exact commit.

4. Guard the branch/version mismatch

scripts/release.js already refuses latest without --allow-latest and refuses mixed channels. Worth adding one more: when running in CI, assert the derived tag matches the branch name.

const branch = process.env.GITHUB_REF_NAME
if (branch && ['alpha','beta','rc'].includes(branch) && branch !== tag) {
  die(`Branch "${branch}" would publish under "${tag}". Align the versions or push to the right branch.`)
}

That catches the realistic mistake: merging into alpha while the manifests still say -beta.1.

5. Retire the manual path

Once this is green, pnpm release stays as the local escape hatch but stops being the normal route. The execFileSync TTY problem then does not matter, since CI never sees a 2FA prompt.

Migration

1. Land release.yml on v10.
2. git branch alpha v10 && git push origin alpha — first push publishes 10.0.0-alpha.4 (or whatever the manifests say).
3. Confirm provenance appears: npm view @react-three/fiber@alpha should show a GitHub Actions publisher, as the canaries do.
4. Repeat for beta when the time comes; no workflow change needed.

Verifying it worked

The tell is provenance. Today:

10.0.0-canary.611635d   by GitHub Actions   provenance: YES
10.0.0-alpha.3          by dennissmolek     provenance: none

After this, every prerelease should look like the first line.

Open decision

Whether to adopt semantic-release as drei does. It would also take over version bumping and changelog generation from commit messages — a much larger change, and this repo's changelogs carry judgment that was hand-corrected as recently as #3842. Recommend branch-triggered publishing with the existing script first, and treating semantic-release as a separate question.

[DennisSmolek]

Promoting one thing out of the YAML in the spec above, because it is buried in a code comment and it fails silently rather than loudly.

The step order is load-bearing

pnpm run ci  →  pnpm build  →  pnpm verify-bundles  →  pnpm verify-types

pnpm run ci is:

pnpm build && pnpm verify-bundles && pnpm verify-types && pnpm typecheck
  && pnpm eslint && pnpm dev && pnpm test && pnpm format

Note pnpm dev near the end — that is pnpm stub, which overwrites dist/ with jiti stubs. So when pnpm run ci exits, dist/ is not a build. It is ~5 KB of stub per entry against a real ~660 KB.

Run verify-bundles at that point and it inspects stubs. Publish at that point and you ship stubs.

That is not hypothetical — it is why the manual cut sequence has pnpm build after pnpm run ci and the verifies last. Get it wrong in CI and the failure mode is a published package containing jiti loaders pointing at absolute paths on a runner that no longer exists.

The size floor added in #3830 exists specifically to catch this:

❌ dist/index.mjs is 4.7 KB -- this is a stub, not a build
   Run `pnpm build`. `pnpm dev`/`pnpm stub` overwrite dist with jiti stubs.

So the guard is in place. The point of flagging it here is that the guard only fires if verify-bundles runs after the rebuild — sequencing it before, or relying on the copy that ran inside pnpm run ci, means nothing checks the artifact that actually gets published.