[release] consolidate release and release-snapshot into one workflow for Trusted Publishing

.github/workflows/release.yml

@@ -1,3 +1,43 @@
+# This workflow handles two flows:
+#
+# 1. Normal release (default)
+#    Triggered by pushes to `main`. Uses changesets/action to either open a
+#    "Version Packages" PR or, when such a PR is merged, publish to npm.
+#
+# 2. Snapshot release (manual, opt-in)
+#    Triggered by running this workflow via workflow_dispatch with the
+#    `snapshot` input set to true.
+#
+#    A snapshot release is useful when you want to try out changes on a pull
+#    request before making a full release and without entering pre-release mode.
+#    Changesets force pre-release mode across all packages in the monorepo,
+#    which blocks stable releases of every package until pre-release is exited,
+#    so we use snapshots instead.
+#
+#    Snapshot releases are published under the `snapshot` dist-tag with versions
+#    like 0.4.0-579bd13f-20230913164912 (the version that would be generated,
+#    the commit short sha, and a timestamp).
+#
+#    How to create one:
+#      - Push your branch to GitHub.
+#      - Make sure the branch has a changeset committed (`pnpm changeset`).
+#      - Open Actions > Release > "Run workflow", select your branch, tick
+#        "snapshot", and run.
+#      - In the run's logs find the "Create Snapshot Release" step. The last
+#        line shows the published version, e.g.
+#          @vercel/blob@2.3.4-579bd13-20230913164912
+#      - Install with `pnpm add @vercel/blob@<that version>` or
+#        `pnpm add @vercel/blob@snapshot` for the latest snapshot.
+#
+# Authentication: this workflow publishes to npm via Trusted Publishing (OIDC),
+# not a long-lived NPM_TOKEN. Each package that should be published from this
+# workflow must have a Trusted Publisher configured on npmjs.com pointing at
+# this repo and the `release.yml` workflow filename. See:
+#   https://docs.npmjs.com/trusted-publishers
+# Trusted publishing requires Node >= 22.14.0 and npm >= 11.5.1, which is why
+# we pin `node-version: latest` here. The `id-token: write` permission below
+# is what allows GitHub Actions to mint the OIDC token npm uses to verify us.
+
 name: Release
 
 env:
@@ -11,9 +51,20 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
+    inputs:
+      snapshot:
+        description: "Publish a snapshot release from the selected branch (under the `snapshot` dist-tag) instead of running the normal release flow. Requires a changeset on the branch."
+        type: boolean
+        default: false
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
+permissions:
+  contents: write       # version commits + GitHub releases (changesets/action)
+  pull-requests: write  # "Version Packages" PR (changesets/action)
+  id-token: write       # OIDC token for npm Trusted Publishing
+
 jobs:
   release:
     name: Release
@@ -27,13 +78,16 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version-file: '.node-version'
-          cache: 'pnpm'
+          node-version: latest
+          registry-url: "https://registry.npmjs.org"
+          cache: "pnpm"
 
       - name: Install Dependencies
         run: pnpm install
 
+      # ----- Normal release (push to main, or manual run without snapshot) -----
       - name: Create Release Pull Request or Publish to npm
+        if: ${{ inputs.snapshot != true }}
         id: changesets
         uses: changesets/action@v1
         with:
@@ -42,4 +96,24 @@ jobs:
           version: pnpm version-packages
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN_ELEVATED }}
+
+      # ----- Snapshot release (manual, when `snapshot` input is true) -----
+      - name: Add SHORT_SHA env property with commit short sha
+        if: ${{ inputs.snapshot == true }}
+        run: echo "SHORT_SHA=`echo ${{ github.sha }} | cut -c1-7`" >> $GITHUB_ENV
+
+      - name: Version Packages (snapshot)
+        if: ${{ inputs.snapshot == true }}
+        run: pnpm changeset version --snapshot ${SHORT_SHA}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build (snapshot)
+        if: ${{ inputs.snapshot == true }}
+        run: pnpm build
+
+      - name: Create Snapshot Release
+        if: ${{ inputs.snapshot == true }}
+        run: pnpm changeset publish --no-git-tag --tag snapshot
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}