Merge pull request #270 from knockout/bmh/sc-trusted-publishing

brianmhunt · web-flow · commit adad876f6509 · 2026-04-01T12:00:30.000-02:30
release: adopt npm trusted publishing
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,58 +1,100 @@
 # Automated release via Changesets.
 #
 # On push to main:
-#   - If there are unreleased changesets, opens/updates a "Version Packages"
+#   - If there are unreleased changesets, opens/updates a release version
 #     PR that bumps versions and updates changelogs.
-#   - If that PR is merged (no remaining changesets), builds and publishes
-#     to npm.
+#   - If there are no unreleased changesets, builds, tests, and publishes
+#     to npm from a separate least-privilege job.
 #
-# Requires an NPM_TOKEN secret with publish access to the @tko scope.
+# Requires npm trusted publisher configuration for the @tko packages.
+# Publish auth comes from GitHub Actions OIDC, not a long-lived npm token.
 name: Release
 
 on:
   push:
     branches: [main]
-  workflow_dispatch:
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:
-  release:
+  prepare-release:
+    name: Prepare Release
     runs-on: ubuntu-latest
 
     permissions:
       contents: write
       pull-requests: write
+
+    outputs:
+      has_changesets: ${{ steps.changesets.outputs.hasChangesets }}
+
+    steps:
+      - name: Checkout code
+        # actions/checkout v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - name: Setup Node.js
+        # actions/setup-node v6.3.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f
+        with:
+          # npm trusted publishing requires npm CLI 11.5.1+, which is available
+          # on the current Node 24 line.
+          node-version: 24.x
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Create or update version PR
+        id: changesets
+        # changesets/action v1.5.3
+        uses: changesets/action@e0145edc7d9d8679003495b11f87bd8ef63c0cba
+        with:
+          version: npx changeset version
+          title: 'chore: version packages'
+          commit: 'chore: version packages'
+          # Signed GitHub API commits are preferable to git-cli pushes for the
+          # automated version PR branch.
+          commitMode: github-api
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    name: Publish to npm
+    needs: prepare-release
+    if: needs.prepare-release.outputs.has_changesets == 'false'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
       id-token: write
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        # actions/checkout v6.0.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        # actions/setup-node v6.3.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f
         with:
-          node-version: 22.x
+          # npm trusted publishing requires npm CLI 11.5.1+, which is available
+          # on the current Node 24 line.
+          node-version: 24.x
           cache: 'npm'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
 
       - name: Build all packages
         run: make
 
       - name: Run tests
         run: make test-headless
 
-      - name: Create release PR or publish
-        uses: changesets/action@v1
-        with:
-          version: npx changeset version
-          publish: npx changeset publish --provenance
-          title: 'chore: version packages'
-          commit: 'chore: version packages'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Publish packages
+        # npm generates provenance attestations automatically during trusted
+        # publishing from GitHub Actions.
+        run: npx changeset publish
diff --git a/AGENTS.md b/AGENTS.md
@@ -126,15 +126,11 @@ This creates a changeset file in `.changeset/` that gets committed with your PR.
 1. Push to main triggers `.github/workflows/release.yml`
 2. If unreleased changesets exist, the action opens a "Version Packages" PR
 3. Review the PR (it bumps versions and updates changelogs)
-4. Merge it to publish to npm
+4. Merge it to publish to npm via GitHub Actions OIDC trusted publishing
 
-**Manual release** (fallback):
-```bash
-make repackage       # Sync package.json metadata across packages
-lerna version        # Bump versions (interactive)
-make                 # Rebuild everything
-lerna publish from-package  # Publish to npm
-```
+Avoid manual workstation publishes. If release CI is unavailable, fix the
+workflow or npm trusted publisher configuration rather than bypassing it with a
+long-lived publish token.
 
 ## Plans
 
diff --git a/README.md b/README.md
@@ -54,7 +54,8 @@ It's available as `@tko/build.knockout`, and over CDN:
 | $ `make` | **Currently TKO use a make file** / no scripts at package.json |
 | $ `make test` | Run all tests with electron. See below. |
 | $ `make test-headless` | Run all tests with chromium. See below. |
-| $ `lerna publish` | Bump versions and publish to npm registry |
+| $ `npx changeset add` | Add a changeset for package behavior changes in your PR |
+| Release workflow | On merge to `main`, CI opens or updates a version PR; when that version PR is merged and there are no remaining changesets, CI publishes from GitHub Actions via npm trusted publishing |
 | $ `make test-coverage` | Run all tests and create a code coverage report |
 
 Checkout the `Makefile` for more commands that can be executed with `make {command}`.
diff --git a/plans/build-and-release-certainty.md b/plans/build-and-release-certainty.md
@@ -6,15 +6,15 @@ releases without manual verification of every detail.
 
 ---
 
-## Current State
+## Original State
 
 - 25-package Lerna monorepo, fully TypeScript, built with esbuild + Make
 - ~89% test coverage across 143 test files with Karma
 - 7 GitHub Actions workflows (build, test, lint, format, TypeScript, CodeQL, docs deploy)
 - ESLint + Prettier enforced on PRs
 - Manual release via `lerna version` + `lerna publish`
 
-## Gaps
+## Original Gaps
 
 | Area | Risk |
 |------|------|
@@ -71,7 +71,8 @@ to npm.
 - Builds all packages and runs tests
 - If unreleased changesets exist, opens/updates a version PR
 - If version PR is merged, publishes to npm
-- Requires `NPM_TOKEN` secret in GitHub repo settings
+- Uses npm trusted publishing via GitHub Actions OIDC
+- Requires trusted publisher configuration for the public `@tko/*` packages on npm
 
 ---
 
@@ -86,8 +87,8 @@ to npm.
 
 ### 3.2 Add npm provenance to publishing ✅ DONE
 
-Release workflow publishes with `--provenance` flag so users can verify
-packages were built in CI.
+When publishing through npm trusted publishing from GitHub Actions, npm
+automatically emits provenance attestations for public packages.
 
 ### 3.3 Add `npm audit` to CI ✅ DONE
 
diff --git a/plans/trusted-publishing.md b/plans/trusted-publishing.md
@@ -0,0 +1,75 @@
+# Plan: Trusted Publishing for npm Releases
+
+**Goal**: Move TKO npm publishing from long-lived `NPM_TOKEN` authentication to
+npm trusted publishing via GitHub Actions OIDC.
+
+---
+
+## Current State
+
+- `.github/workflows/release.yml` already grants `id-token: write`
+- Releases still document and use `NPM_TOKEN`
+- Workflow publishes through `changesets/action`
+- Current workflow uses Node 22, but npm trusted publishing now requires
+  npm CLI `11.5.1+`
+
+## Desired State
+
+- Release publishing works from GitHub-hosted runners without a write token
+- The workflow uses a Node/npm combination compatible with npm trusted publishing
+- Release docs no longer tell maintainers to configure `NPM_TOKEN`
+- The migration path notes the remaining manual npm-side setup:
+  trusted publisher registration and token revocation after verification
+
+## Implementation
+
+### 1. Workflow
+
+- Update the release workflow to use a trusted-publisher-compatible Node version
+- Split version-PR automation from npm publishing so the publish job can run
+  with read-only repository permissions plus OIDC
+- Switch CI dependency installation to `npm ci` for lockfile-enforced releases
+- Pin third-party GitHub Actions by commit SHA
+- Remove publish-time `NPM_TOKEN` / `NODE_AUTH_TOKEN` env wiring
+- Keep `id-token: write`
+- Keep Changesets for release PR creation
+- Drop explicit `--provenance` because npm generates provenance automatically
+  during trusted publishing
+
+### Why split prepare vs publish
+
+Many Changesets-based repositories keep release-PR creation and npm publishing
+in one job. That is simpler, but it forces the publish path to carry both
+repository write access and package-publish credentials at the same time.
+
+For TKO, the split is intentional:
+
+- `prepare-release` needs repository write permissions to open/update the
+  version PR branch
+- `publish` only needs `contents: read` plus `id-token: write` for npm OIDC
+- this keeps the npm publish path on least privilege while preserving the
+  standard Changesets PR flow on `main`
+
+This is a better fit for trusted publishing than the default single-job
+Changesets pattern.
+
+### 2. Repository docs
+
+- Update the build/release plan to describe trusted publishing instead of
+  token-based publishing
+- Update the README release guidance so maintainers do not follow the old
+  `lerna publish` path
+
+### 3. Follow-up outside the repo
+
+- Configure trusted publishers for the public `@tko/*` packages on npm
+- Verify one publish from GitHub Actions
+- After verification, disable token-based publishing for those packages and
+  revoke unneeded automation tokens
+
+## Verification
+
+- Review `.github/workflows/release.yml` for OIDC-only publish auth
+- Confirm no remaining repo docs require `NPM_TOKEN` for publishing
+- Confirm the workflow now targets a Node/npm version that meets npm trusted
+  publishing requirements
