Add npm auth setup for trusted publishing (OIDC) and token-based auth

Bumpy now automatically handles npm authentication before publishing:
- Detects GitHub Actions OIDC and validates npm version (>= 11.5.1)
- Auto-configures .npmrc when NPM_TOKEN/NODE_AUTH_TOKEN env vars are set
- Warns with actionable suggestions when no auth is detected in CI

Updated workflow examples to show both OIDC (primary) and token-based auth.

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

Author: theoephraim

.github/workflows/release.yaml

@@ -9,12 +9,13 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-      id-token: write
+      id-token: write # required for npm trusted publishing (OIDC)
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
+      - run: npm install -g npm@latest # npm >= 11.5.1 required for trusted publishing
       - run: bun install
       # Build first since we use the local workspace package instead of the published one
       - run: bun run --filter @varlock/bumpy build

README.md

@@ -95,10 +95,10 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 ```
 
-**Release** — create a "Version Packages" PR on merge to main:
+**Release** — create a "Version Packages" PR on merge to main, publish when merged:
 
 ```yaml
-# .github/workflows/bumpy-release.yml
+# .github/workflows/bumpy-release.yml — trusted publishing (OIDC, no secret needed)
 name: Bumpy Release
 on:
   push:
@@ -110,18 +110,51 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-      id-token: write
+      id-token: write # required for npm trusted publishing (OIDC)
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
+      - run: npm install -g npm@latest # npm >= 11.5.1 required for trusted publishing
       - run: bun install
       - run: bunx @varlock/bumpy ci release
         env:
           GH_TOKEN: ${{ github.token }}
 ```
 
+> **Trusted publishing setup:** Configure each package on [npmjs.com](https://docs.npmjs.com/trusted-publishers/) → Package Settings → Trusted Publishers → GitHub Actions. Specify your org/user, repo, and the workflow filename (`bumpy-release.yml`). No `NPM_TOKEN` secret needed.
+
+<details>
+<summary>Alternative: token-based auth (NPM_TOKEN secret)</summary>
+
+```yaml
+# .github/workflows/bumpy-release.yml — token-based auth
+name: Bumpy Release
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bunx @varlock/bumpy ci release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+</details>
+
 Or use `bumpy ci release --auto-publish` to version + publish directly without a PR.
 
 ## AI Integration

llms.md

@@ -586,7 +586,7 @@ jobs:
 ```
 
 ```yaml
-# .github/workflows/bumpy-release.yml
+# .github/workflows/bumpy-release.yml — trusted publishing (OIDC, no secret needed)
 name: Bumpy Release
 on:
   push:
@@ -598,22 +598,47 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-      id-token: write # for npm provenance
+      id-token: write # required for npm trusted publishing (OIDC)
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
+      - run: npm install -g npm@latest # npm >= 11.5.1 required for trusted publishing
       - run: bun install
-      # Option A: Create a "Version Packages" PR
       - run: bunx @varlock/bumpy ci release
         env:
           GH_TOKEN: ${{ github.token }}
-      # Option B: Auto-publish directly
-      # - run: bunx @varlock/bumpy ci release --auto-publish
-      #   env:
-      #     GH_TOKEN: ${{ github.token }}
-      #     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Trusted publishing setup: configure each package on npmjs.com → Package Settings → Trusted Publishers → GitHub Actions.
+Specify your org/user, repo, and the workflow filename. No NPM_TOKEN secret needed.
+
+Alternative: token-based auth (uses `NPM_TOKEN` secret instead of OIDC):
+
+```yaml
+# .github/workflows/bumpy-release.yml — token-based auth
+name: Bumpy Release
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bunx @varlock/bumpy ci release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
 ### Non-interactive changeset creation (AI/CI)

packages/bumpy/src/core/publish-pipeline.ts

@@ -1,7 +1,9 @@
 import { resolve } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
 import { unlink } from 'node:fs/promises';
 import { readJson, writeJson } from '../utils/fs.ts';
 import { runAsync } from '../utils/shell.ts';
+import { tryRun } from '../utils/shell.ts';
 import { log, colorize } from '../utils/logger.ts';
 import { createTag, tagExists } from './git.ts';
 import { DependencyGraph } from './dep-graph.ts';
@@ -20,6 +22,79 @@ export interface PublishResult {
   failed: { name: string; error: string }[];
 }
 
+/** Check if GitHub Actions OIDC is available (id-token: write permission granted) */
+function isOidcAvailable(): boolean {
+  return !!process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+}
+
+/**
+ * Set up npm authentication for publishing.
+ *
+ * Handles three scenarios:
+ * 1. **Trusted publishing (OIDC)** — GitHub Actions with `id-token: write`.
+ *    npm >= 11.5.1 authenticates automatically via OIDC token exchange.
+ *    No secret needed, but we check the npm version and warn if too old.
+ * 2. **Token-based auth** — `NPM_TOKEN` or `NODE_AUTH_TOKEN` env var.
+ *    Writes a project-level `.npmrc` so npm can authenticate.
+ * 3. **Pre-configured** — user already has `.npmrc` with auth (e.g. via `actions/setup-node`).
+ */
+function setupNpmAuth(rootDir: string, publishManager: string): void {
+  // Only relevant when publishing via npm CLI
+  if (publishManager !== 'npm') return;
+
+  const npmrcPath = resolve(rootDir, '.npmrc');
+  const existingNpmrc = existsSync(npmrcPath) ? readFileSync(npmrcPath, 'utf-8') : '';
+  const hasAuthConfigured = existingNpmrc.includes(':_authToken=');
+
+  // If auth is already configured (e.g. via actions/setup-node), nothing to do
+  if (hasAuthConfigured) {
+    log.dim('  Using existing .npmrc auth configuration');
+    return;
+  }
+
+  // Scenario 1: OIDC trusted publishing
+  if (isOidcAvailable()) {
+    const npmVersion = tryRun('npm --version');
+    if (npmVersion) {
+      const [major, minor, patch] = npmVersion.split('.').map(Number);
+      const meetsMinVersion = major! > 11 || (major === 11 && (minor! > 5 || (minor === 5 && patch! >= 1)));
+      if (!meetsMinVersion) {
+        log.warn(`  npm ${npmVersion} detected — trusted publishing (OIDC) requires npm >= 11.5.1`);
+        log.warn('  Add "npm install -g npm@latest" to your workflow before publishing');
+      } else {
+        log.dim(`  OIDC detected — npm ${npmVersion} will authenticate via trusted publishing`);
+      }
+    }
+    return;
+  }
+
+  // Scenario 2: Token-based auth via environment variable
+  // Support NPM_TOKEN (common convention) by mapping to NODE_AUTH_TOKEN (what npm reads from .npmrc)
+  const token = process.env.NODE_AUTH_TOKEN || process.env.NPM_TOKEN;
+  if (token) {
+    if (process.env.NPM_TOKEN && !process.env.NODE_AUTH_TOKEN) {
+      process.env.NODE_AUTH_TOKEN = token;
+    }
+    const authLine = '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}';
+    if (existingNpmrc) {
+      appendFileSync(npmrcPath, `\n${authLine}\n`);
+    } else {
+      writeFileSync(npmrcPath, `${authLine}\n`);
+    }
+    log.dim('  Configured .npmrc with auth token');
+    return;
+  }
+
+  // No auth detected — warn
+  if (process.env.CI) {
+    log.warn('  No npm authentication detected. Publishing will likely fail.');
+    log.warn('  Options:');
+    log.warn('    • Trusted publishing (OIDC): add `id-token: write` permission + npm >= 11.5.1');
+    log.warn('    • Token auth: set NPM_TOKEN or NODE_AUTH_TOKEN environment variable');
+    log.warn('    • Manual: add `actions/setup-node` with `registry-url` to your workflow');
+  }
+}
+
 /**
  * Publish all packages in the release plan.
  * Order: topological (dependencies published before dependents).
@@ -37,6 +112,9 @@ export async function publishPackages(
   const result: PublishResult = { published: [], skipped: [], failed: [] };
   const publishConfig = config.publish;
 
+  // Set up npm authentication before publishing
+  setupNpmAuth(rootDir, publishConfig.publishManager);
+
   // Resolve "auto" pack manager to detected PM
   const packManager = publishConfig.packManager === 'auto' ? detectedPm : publishConfig.packManager;