ci(release): switch npm publishing to Trusted Publishers (OIDC) (czlonkowski#796)

* ci(release): switch npm publishing to Trusted Publishers (OIDC)

Replace long-lived NPM_TOKEN auth with short-lived OIDC tokens minted
by GitHub Actions via npm Trusted Publishers. Publishes now ship with
provenance attestations linking the package back to the exact workflow
run and commit.

Workflow changes (.github/workflows/release.yml):
- Add `environment: npm-publish` and `permissions: id-token: write` to
  publish-npm
- Upgrade runner npm to >= 11.5.1 (Node 20 bundles npm 10.x; Trusted
  Publishing requires 11.5.1+)
- Drop NODE_AUTH_TOKEN / NPM_TOKEN; add --provenance to npm publish

Docs (docs/AUTOMATED_RELEASES.md):
- Replace NPM_TOKEN setup with Trusted Publisher configuration steps
- Update troubleshooting and security sections

Preflight (scripts/test-release-automation.js):
- Check for id-token: write and environment: npm-publish instead of
  NPM_TOKEN
- Update Next Steps to reference the new auth model

Requires (one-time, before next release):
- npmjs.com: configure Trusted Publisher for repo czlonkowski/n8n-mcp,
  workflow release.yml, environment npm-publish
- GitHub: create environment `npm-publish` (no protection rules needed)
- After first successful release, NPM_TOKEN secret can be deleted

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(release): address Copilot review on PR czlonkowski#796

- Pin runner npm to ^11.5.1 instead of @latest, and echo version after
  install for easier troubleshooting. Avoids exposing the release flow
  to future npm major releases.
- Scope OIDC preflight checks (id-token: write, environment: npm-publish)
  to the publish-npm job block instead of the entire workflow file, so
  the checks can't false-positive on keys belonging to other jobs.

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: czlonkowski

.github/workflows/release.yml

@@ -309,6 +309,10 @@ jobs:
     runs-on: ubuntu-latest
     needs: [detect-version-change, build-and-verify, create-release]
     if: needs.detect-version-change.outputs.version-changed == 'true'
+    environment: npm-publish
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -318,7 +322,11 @@ jobs:
         with:
           node-version: 20
           cache: 'npm'
-          registry-url: 'https://registry.npmjs.org'
+
+      - name: Upgrade npm to >= 11.5.1 (Trusted Publisher support)
+        run: |
+          npm install -g 'npm@^11.5.1'
+          npm --version
 
       - name: Install dependencies
         # See test.yml for the --legacy-peer-deps rationale (mappersmith / diff conflict).
@@ -397,9 +405,7 @@ jobs:
           max_attempts: 3
           command: |
             cd npm-publish-temp
-            npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+            npm publish --access public --provenance
 
       - name: Clean up
         if: always()

docs/AUTOMATED_RELEASES.md

@@ -116,15 +116,29 @@ Set these in GitHub repository settings → Secrets:
 
 | Secret | Description | Required |
 |--------|-------------|----------|
-| `NPM_TOKEN` | NPM authentication token for publishing | ✅ Yes |
+| `DOCKERHUB_USERNAME` | Docker Hub username for image pushes | ✅ Yes |
+| `DOCKERHUB_TOKEN` | Docker Hub access token | ✅ Yes |
 | `GITHUB_TOKEN` | Automatically provided by GitHub Actions | ✅ Auto |
 
-### NPM Token Setup
+NPM publishing uses [npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers) (OIDC) — no `NPM_TOKEN` secret is required.
 
-1. Login to [npmjs.com](https://www.npmjs.com)
-2. Go to Account Settings → Access Tokens
-3. Create a new **Automation** token
-4. Add as `NPM_TOKEN` secret in GitHub
+### NPM Trusted Publisher Setup
+
+The `publish-npm` job authenticates to npm via short-lived OIDC tokens minted by GitHub Actions. This is configured once on the npm side:
+
+1. Login to [npmjs.com](https://www.npmjs.com) as a maintainer of `n8n-mcp`.
+2. Go to the package page → **Settings** → **Trusted Publishers** → **Add publisher**.
+3. Configure:
+   - **Publisher**: GitHub Actions
+   - **Organization or user**: `czlonkowski`
+   - **Repository**: `n8n-mcp`
+   - **Workflow filename**: `release.yml`
+   - **Environment**: `npm-publish`
+4. Save.
+
+The matching GitHub environment must exist (Settings → Environments → `npm-publish`). No protection rules are required, though a required reviewer can be added for an approval gate before each release.
+
+The workflow declares `id-token: write` and `environment: npm-publish` on the `publish-npm` job; `npm publish` detects the OIDC runtime and authenticates automatically. Provenance attestations are published with every release.
 
 ## Testing
 
@@ -230,7 +244,17 @@ The workflow provides comprehensive summaries:
 ```
 Error: 401 Unauthorized
 ```
-**Solution**: Check NPM_TOKEN secret is valid and has publishing permissions.
+or
+```
+npm error code ENEEDAUTH
+npm error need auth This command requires you to be logged in
+```
+**Solution**: Verify the Trusted Publisher configuration on npmjs.com matches the workflow:
+- Repository: `czlonkowski/n8n-mcp`
+- Workflow filename: `release.yml` (filename only, no path)
+- Environment: `npm-publish`
+
+Also confirm the `publish-npm` job in the workflow still has `permissions: id-token: write` and `environment: npm-publish`. Runner npm must be ≥ 11.5.1 — the `Upgrade npm` step handles this.
 
 #### Docker Build Fails
 ```
@@ -282,7 +306,9 @@ Version not incremented
 ## Security
 
 ### Secrets Management
-- NPM_TOKEN has limited scope (publish only)
+- NPM auth uses Trusted Publishers (OIDC) — no long-lived npm token stored in the repo
+- Each release mints a short-lived token scoped to the workflow run
+- Provenance attestations are signed and published with every release, linking the package back to the exact commit + workflow run
 - GITHUB_TOKEN has automatic scoping
 - No secrets are logged or exposed
 

scripts/test-release-automation.js

@@ -419,14 +419,35 @@ class ReleaseAutomationTester {
         }
       }
 
-      // Check for secrets usage
-      if (workflowContent.includes('${{ secrets.NPM_TOKEN }}')) {
-        success('Workflow: NPM_TOKEN secret configured');
+      // Check for npm Trusted Publisher (OIDC) configuration — scoped to the publish-npm job
+      // Slice from "  publish-npm:" to the next job at the same indent (2 spaces, non-space char)
+      const publishNpmMatch = workflowContent.match(/^ {2}publish-npm:\n([\s\S]*?)(?=^ {2}\S|\Z)/m);
+      const publishNpmBlock = publishNpmMatch ? publishNpmMatch[1] : '';
+
+      if (!publishNpmBlock) {
+        error('Workflow: could not locate publish-npm job block for OIDC checks');
+        this.errors.push('publish-npm job not found in workflow');
       } else {
-        warning('Workflow: NPM_TOKEN secret may be missing');
-        this.warnings.push('NPM_TOKEN secret may need to be configured');
+        if (/\bid-token:\s*write\b/.test(publishNpmBlock)) {
+          success('Workflow: publish-npm has id-token: write permission (OIDC)');
+        } else {
+          error('Workflow: publish-npm is missing id-token: write permission');
+          this.errors.push('Trusted Publishing requires id-token: write on publish-npm job');
+        }
+
+        if (/\benvironment:\s*npm-publish\b/.test(publishNpmBlock)) {
+          success('Workflow: publish-npm uses npm-publish environment');
+        } else {
+          error('Workflow: publish-npm is missing environment: npm-publish');
+          this.errors.push('Trusted Publishing requires environment: npm-publish on publish-npm job');
+        }
       }
-      
+
+      if (workflowContent.includes('${{ secrets.NPM_TOKEN }}')) {
+        warning('Workflow: stale NPM_TOKEN reference found — Trusted Publishing makes this unnecessary');
+        this.warnings.push('Remove ${{ secrets.NPM_TOKEN }} from workflow now that OIDC is used');
+      }
+
       if (workflowContent.includes('${{ secrets.GITHUB_TOKEN }}')) {
         success('Workflow: GITHUB_TOKEN secret configured');
       } else {
@@ -535,9 +556,11 @@ class ReleaseAutomationTester {
 
     // Next steps
     log('\n📋 Next Steps:', 'cyan');
-    log('1. Ensure all secrets are configured in GitHub repository settings:', 'cyan');
-    log('   • NPM_TOKEN (required for npm publishing)', 'cyan');
-    log('   • GITHUB_TOKEN (automatically available)', 'cyan');
+    log('1. Ensure GitHub repository settings are configured:', 'cyan');
+    log('   • Secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN', 'cyan');
+    log('   • Environment "npm-publish" exists (Settings → Environments)', 'cyan');
+    log('   • npm Trusted Publisher configured on npmjs.com (no NPM_TOKEN secret needed)', 'cyan');
+    log('   • GITHUB_TOKEN is provided automatically', 'cyan');
     log('\n2. To trigger a release:', 'cyan');
     log('   • Update version in package.json', 'cyan');
     log('   • Update changelog in docs/CHANGELOG.md', 'cyan');