npm OIDC Trusted Publishing Setup

Overview

This skill helps configure npm Trusted Publishing using OpenID Connect (OIDC), eliminating the need for 90-day rotating npm tokens in GitHub Actions. Instead, GitHub cryptographically proves the workflow's identity to npm.

When to Use This Skill

• •Setting up GitHub Actions to publish npm packages without tokens
• •Debugging ENEEDAUTH or 404 Not Found errors during npm publish
• •Migrating from npm token-based to OIDC-based authentication
• •Configuring automated versioning with Changesets

Prerequisites

1. •npm Account with 2FA enabled (required for Trusted Publishing)
2. •GitHub repository with Actions enabled
3. •Node.js 24+ (includes npm 11.5.1+ which supports OIDC)
4. •Package already published to npm at least once

Step-by-Step Setup

1. Configure npm Trusted Publisher

Go to your package settings on npmjs.com:

URL: https://www.npmjs.com/package/@YOUR_SCOPE/PACKAGE_NAME/access

1. •Scroll to "Trusted Publisher" section
2. •Select "GitHub Actions" as publisher
3. •Fill in the form EXACTLY (case-sensitive, no extra spaces):

1. •CRITICAL: Click "Set up connection" button to activate
2. •Verify you see the active connection listed with GitHub icon

2. Configure GitHub Actions Workflow

Create .github/workflows/release.yml:

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write  # Required for OIDC

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'pnpm'
          # DO NOT set registry-url - conflicts with OIDC

      - run: pnpm install --frozen-lockfile
      - run: pnpm build

      - name: Publish to npm with OIDC
        run: npm publish --provenance --access public
        env:
          # No NPM_TOKEN needed - OIDC handles auth

Key Points:

• •✅ id-token: write permission is required
• •✅ Node.js 24+ for npm 11.5.1+ (OIDC support)
• •❌ DO NOT set registry-url in setup-node (creates .npmrc that conflicts)
• •❌ DO NOT use NODE_AUTH_TOKEN environment variable
• •✅ --provenance flag helps npm detect OIDC

3. Verify No Conflicting Configuration

Check for files that might interfere:

1. •

   No npm tokens in GitHub Secrets:

   • •Settings → Secrets → Actions
   • •Should have NO NPM_TOKEN secret
2. •

   No auth in .npmrc:

   • •.npmrc should only have config, not authentication
   • •Remove any //registry.npmjs.org/:_authToken= lines
3. •

   Correct repository URL in package.json:

   json

   {
     "repository": {
       "type": "git",
       "url": "https://github.com/YOUR_ORG/YOUR_REPO.git"
     }
   }
   

Troubleshooting

Error: ENEEDAUTH - need auth

Cause: npm cannot authenticate with OIDC

Solutions:

1. •

   Verify Trusted Publisher is ACTIVE (not just configured)

   • •Go to npmjs.com package settings
   • •You should see the connection listed with Edit/Delete buttons
   • •If you see an empty form, you need to click "Set up connection"
2. •

   Check for typos in npm configuration:

   • •Click "Edit" on your Trusted Publisher
   • •Verify NO extra spaces in workflow field
   • •Verify exact capitalization matches GitHub
3. •

   Verify OIDC environment: Add debug step to workflow:

   yaml

   - name: Debug OIDC
     run: |
       npm --version
       echo "OIDC URL set: ${{ env.ACTIONS_ID_TOKEN_REQUEST_URL != '' }}"
   

Error: 404 Not Found - PUT https://registry.npmjs.org/@scope/package

Cause: npm Trusted Publisher configuration doesn't match running workflow

Solutions:

1. •

   Configuration mismatch - Verify EXACT match:

   • •Organization: must match GitHub URL (case-sensitive)
   • •Repository: must match repo name (case-sensitive)
   • •Workflow: must be exactly release.yml (no path, no spaces)
   • •Environment: must be empty (not "blank", not spaces)
2. •

   Workflow file renamed:

   • •If you renamed release.yml to something else, update npm config
3. •

   Environment field has value:

   • •If npm config has environment set to "production", add to workflow:
     yaml

     jobs:
       release:
         environment: production  # Must match npm config
     

Error: Access token expired or revoked

Cause: npm is trying to use token auth instead of OIDC

Solutions:

1. •

   Remove registry-url from setup-node:

   yaml

   # ❌ WRONG - creates .npmrc with token
   - uses: actions/setup-node@v4
     with:
       registry-url: 'https://registry.npmjs.org'
   
   # ✅ CORRECT - allows OIDC
   - uses: actions/setup-node@v4
     with:
       node-version: 24
       cache: 'pnpm'
   

2. •

   Delete NPM_TOKEN from GitHub Secrets

3. •

   Check for .npmrc with auth token in repository

Automated Versioning with Changesets

Install Changesets

pnpm add -D @changesets/cli @changesets/changelog-github
pnpm changeset init

Configure .changeset/config.json:

{
  "changelog": ["@changesets/changelog-github", {
    "repo": "YOUR_ORG/YOUR_REPO"
  }],
  "access": "public",
  "baseBranch": "main"
}

Workflow with Changesets

- name: Create Release PR or Publish
  uses: changesets/action@v1
  with:
    version: pnpm changeset version
    publish: pnpm changeset publish
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    # No NPM_TOKEN - using OIDC

Using Changesets

1. Make code changes

2. Create a changeset (not a version bump!):

pnpm changeset
# Select: patch | minor | major
# Write summary of changes

3. Commit the changeset file:

git add .changeset/*.md
git commit -m "feat: add new feature"
git push

4. Workflow creates "Version Packages" PR automatically

5. Merge PR → Auto-publishes to npm via OIDC

Benefits of OIDC Publishing

✅ No token management - No 90-day rotation ✅ Better security - Short-lived, workflow-specific tokens ✅ No secrets - Nothing to leak or expose ✅ Automatic provenance - Cryptographic proof of origin ✅ Easier onboarding - Team members don't need npm tokens

Verification Checklist

Before asking for help, verify:

• • npm package has Trusted Publisher ACTIVE (not just configured)
• • Clicked "Set up connection" button on npmjs.com
• • Workflow has id-token: write permission
• • Using Node.js 24+ in workflow
• • NO registry-url in setup-node
• • NO NPM_TOKEN in GitHub Secrets
• • Organization/Repository/Workflow match EXACTLY (case-sensitive)
• • Environment field is completely empty (not "blank")
• • Workflow file is named exactly release.yml

Common Questions

Q: Do I still need npm tokens for local development? A: Yes, OIDC only works in CI/CD. Local npm publish requires npm login.

Q: Can I use OIDC with private packages? A: Yes, OIDC works with both public and private packages.

Q: Does OIDC work with monorepos? A: Yes, but each package needs its own Trusted Publisher configuration.

Q: Can I have multiple workflows publish the same package? A: Yes, configure multiple Trusted Publishers (one per workflow file).

Resources

• •npm Trusted Publishing Docs
• •GitHub OIDC Documentation
• •Changesets Documentation