Migrate npm publishing to trusted publishers (OIDC)

[themightychris]

Summary

Migrate from token-based npm publishing to npm trusted publishers using OIDC authentication. This eliminates the need to manage NPM_TOKEN secrets and provides provenance attestations.

Benefits

• No secrets to manage/rotate
• Provenance attestations automatically generated
• Verified badge on npm showing the package came from this GitHub repo
• More secure: short-lived, workflow-specific credentials that cannot be exfiltrated

Migration Steps

1. Update the GitHub Actions workflow

jobs:
  publish-npm:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write  # Required for OIDC
    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: '22.x'
        registry-url: 'https://registry.npmjs.org'

    - name: Upgrade npm for trusted publishing
      run: npm install -g npm@latest  # Requires npm v11.5.1+

    # ... build steps ...

    - run: npm publish --provenance --access public
    # Note: No NODE_AUTH_TOKEN needed!

Key changes:

• Add id-token: write permission
• Add step to upgrade npm (Node 22.x ships with npm 10.x, but trusted publishing requires npm 11.5.1+)
• Use npm publish --provenance --access public without NODE_AUTH_TOKEN

2. Configure trusted publisher on npmjs.com

1. Go to your package settings on npmjs.com (e.g., https://www.npmjs.com/package/git-client/access)
2. Under "Trusted Publisher", add a new publisher:
   • Organization or user: JarvusInnovations
   • Repository: git-client
   • Workflow filename: publish-npm.yml (or whatever your workflow is named)
   • Environment: (leave blank unless using GitHub environments)

3. Update package.json repository field

The repository field in package.json must match the GitHub repo where the workflow runs:

{
  "repository": "https://github.com/JarvusInnovations/git-client"
}

If this doesn't match, you'll get an error like:

Error verifying sigstore provenance bundle: Failed to validate repository information

4. Optional: Increase security

On npmjs.com, select "Require two-factor authentication and disallow tokens (recommended)" to ensure only trusted publishers can publish.

5. Clean up

After verifying the new workflow works, delete the NPM_TOKEN secret from GitHub repo settings.

References

• npm Trusted Publishers docs
• GitHub Changelog announcement