chore: migrate release workflows to npm Trusted Publishers

Because the Trusted Publishers mechanism only supports one publishing
workflow per repo, this requires unifying the two release workflows
into a single one, with a beta parameter to distinguish between them.

Co-authored-by: [email protected]

Author: Copilot

.github/workflows/release-beta.yml

@@ -2,6 +2,12 @@ name: Release
 
 on:
   workflow_dispatch:
+    inputs:
+      beta:
+        description: "Release as beta prerelease"
+        required: false
+        default: true
+        type: boolean
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
@@ -11,26 +17,75 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
+      # Required for npm Trusted Publishers via GitHub OIDC
+      # See: https://docs.npmjs.com/trusted-publishers
       id-token: write
 
     steps:
+      # Beta-specific: Check RELEASE_PAT secret exists (only for beta releases)
+      - name: Check RELEASE_PAT secret exists
+        if: inputs.beta
+        run: |
+          if [ -z "${{ secrets.RELEASE_PAT }}" ]; then
+            echo "Error: RELEASE_PAT secret is required but not set for beta releases."
+            echo "This workflow requires a Personal Access Token to bypass branch protection rules."
+            echo "See PUBLISHING.md."
+            exit 1
+          fi
+
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          # Beta releases use PAT to bypass branch protection rules when committing and pushing
+          token: ${{ inputs.beta && secrets.RELEASE_PAT || secrets.GITHUB_TOKEN }}
+
+      # Beta-specific: Branch check is necessary for manual triggers (workflow_dispatch) to ensure
+      # we only push version changes to main. If using automatic push triggers,
+      # the trigger itself would enforce the branch, but manual triggers can run
+      # from any branch.
+      - name: Check branch is main
+        if: inputs.beta
+        run: |
+          if [ "${{ github.ref }}" != "refs/heads/main" ]; then
+            echo "Error: Beta releases must be run on the main branch"
+            exit 1
+          fi
+
       - uses: actions/setup-node@v6
         with:
           node-version: 20
           cache: "npm"
+          # registry-url is required for npm Trusted Publishers
           registry-url: "https://registry.npmjs.org"
+
       - run: npm ci
       - run: npm run check
 
-      - name: Create .npmrc
+      # Beta-specific: Enter prerelease mode (if not already)
+      - name: Enter prerelease mode (if not already)
+        if: inputs.beta
         run: |
-          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
-          echo "@hypercerts-org:registry=https://registry.npmjs.org/" >> .npmrc
+          if [ ! -f .changeset/pre.json ]; then
+            npx changeset pre enter beta
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add .changeset/pre.json
+            git commit -m "chore: enter beta prerelease mode"
+          fi
 
+      # Beta-specific: Version packages manually
+      - name: Version packages
+        if: inputs.beta
+        run: npm run version-packages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # No .npmrc creation needed - npm Trusted Publishers uses GitHub OIDC tokens
+      # automatically via the id-token: write permission and registry-url configuration
+
+      # Stable release: Use changesets/action which handles versioning and publishing
       - name: Create Release Pull Request or Publish
+        if: ${{ !inputs.beta }}
         id: changesets
         uses: changesets/action@e0145edc7d9d8679003495b11f87bd8ef63c0cba # v1.5.3
         with:
@@ -42,6 +97,26 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_CONFIG_PROVENANCE: true
 
+      # Beta-specific: Publish beta packages directly
+      - name: Publish beta packages
+        if: inputs.beta
+        # Use npm run release to match regular releases - it runs check before publishing
+        # to ensure validation after versioning (package.json/changelog changes)
+        run: npm run release
+        env:
+          NPM_CONFIG_PROVENANCE: true
+
+      # Beta-specific: Commit and push version changes
+      - name: Commit and push version changes
+        if: inputs.beta
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --staged --quiet || git commit -m "chore: version packages (beta)"
+          git push
+
+      # Stable release: Log published packages
       - name: Log published packages
-        if: steps.changesets.outputs.published == 'true'
+        if: ${{ !inputs.beta && steps.changesets.outputs.published == 'true' }}
         run: echo "Published - ${{ steps.changesets.outputs.publishedPackages }}"

.github/workflows/release.yml

@@ -26,8 +26,15 @@ Before publishing, ensure you have:
      - **Note:** Ensure branch protection rules allow the token to bypass
        protection (uncheck "Do not allow bypassing the above settings" or
        add the token as an allowed actor)
-   - `NPM_TOKEN`: npm access token with publish permissions for
-     `@hypercerts-org` scope
+
+2. **npm Trusted Publisher configured:**
+   - The workflow uses npm Trusted Publishers via GitHub OIDC for secure,
+     token-less publishing
+   - Configure on npmjs.com: Package settings → Publishing access → Add a
+     GitHub Actions publisher
+   - Workflow name: `Release`
+   - See: <https://docs.npmjs.com/trusted-publishers>
+   - No `NPM_TOKEN` secret is required
 
 ## Adding Changesets
 
@@ -65,6 +72,7 @@ To publish a stable release to npm:
 3. **Run the workflow:**
    - Click "Run workflow"
    - Select the branch (typically `main`)
+   - **Uncheck "Release as beta prerelease" (it is checked by default)**
    - Click "Run workflow" to start
 
 4. **What happens:**
@@ -81,11 +89,12 @@ To publish a beta/prerelease version:
    - Go to the "Actions" tab
 
 2. **Select the workflow:**
-   - Choose "Release Beta"
+   - Choose "Release" from the workflow list
 
 3. **Run the workflow:**
    - Click "Run workflow"
    - Select the branch (must be `main`)
+   - **Leave "Release as beta prerelease" checked (it is checked by default)**
    - Click "Run workflow"
 
 4. **What happens:**
@@ -95,7 +104,7 @@ To publish a beta/prerelease version:
    - Version format: `0.9.0-beta.1`, `0.9.0-beta.2`, etc.
    - Commits and pushes version changes back to the repository
 
-**Note:** This workflow requires the `RELEASE_PAT` secret to bypass
+**Note:** Beta releases require the `RELEASE_PAT` secret to bypass
 branch protection rules when pushing version changes.
 
 ## Validating Releases (PRs)