Npm Trusted Publishing

npm Trusted Publishing

Moves a GitHub Actions release from a stored NPM_TOKEN to npm trusted publishing. GitHub signs a short-lived OIDC token for the run, and npm exchanges it for a publish token. It also diagnoses the misleading errors a half-finished migration produces. From January 2027, granular tokens that bypass 2FA can no longer publish directly (npm docs).

When to Use This Skill

• The user wants to remove NPM_TOKEN / NODE_AUTH_TOKEN from a release workflow or set up OIDC or provenance publishing.

• A CI publish fails with ENEEDAUTH, 404 Not Found - PUT https://registry.npmjs.org/... or E422 ... repository.url.

• Release logs show npm notice npm tokens that bypass 2FA are being restricted.

Checklist (all must hold)

Work through every item. Missing any one of them produces the errors above.

1. OIDC permission: the publishing job has permissions: id-token: write. If the job had no permissions block, keep the scopes it needs, such as contents: write for tags and releases or pull-requests: write for changesets. Adding a block drops every scope you don't list.

2. npm 11.5.1 or newer runs the publish. Node 24 ships it. Node 22 ships npm 10, so add npm install -g npm@^11.5.1 (or a newer pinned major) before publishing. pnpm 10 hands the publish to npm, so the same rule applies. Yarn Berry needs 4.10.3+.

3. No token reaches the publish step. Remove NODE_AUTH_TOKEN, NPM_TOKEN and YARN_NPM_AUTH_TOKEN from the step, the job and the workflow env, and delete script lines that write _authToken or npmAuthToken. npm tries OIDC first but falls back to a configured token, so a leftover token keeps the old credential in use. Keep a read-only token only on install steps that need private packages.

4. actions/setup-node has registry-url: https://registry.npmjs.org.

5. package.json repository.url names the same GitHub repo, for example git+https://github.com/OWNER/REPO.git, plus directory for workspace packages. A mismatch gives E422.

6. A trusted publisher exists on npm for each package (npmjs.com → package → Settings → Trusted publishing), or with npm 11.15+: npm trust github <pkg> --repo OWNER/REPO --file release.yml --allow-publish --yes

   • The workflow file name must match exactly; it is case-sensitive and includes .yml.

   • For a reusable workflow, use the calling workflow's file name, and grant id-token: write in the caller too.

   • If the job uses environment:, set the same environment on the publisher.

   • A package that doesn't exist yet must be published once by hand first.

7. GitHub-hosted runner. Self-hosted runners can't use trusted publishing.

Security Rules

• Untrusted triggers: never add id-token: write to a job in a workflow triggered by pull_request_target, issue_comment, workflow_run or discussion. It would let outsiders exchange an OIDC token and publish. Move publishing to release, push (tags) or workflow_dispatch.

• Dry runs: npm publish --dry-run and npm pack jobs don't publish, so they need no id-token and no trusted publisher.

• The old token: delete the secret (gh secret delete NPM_TOKEN) and revoke it on npmjs.com only after the first tokenless release succeeds.

Error Guide

Example

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --access public   # no NODE_AUTH_TOKEN

Automating It

go-tokenless (MIT) applies this checklist to an existing repository. Use it when the user wants the edits made for them.

• npx go-tokenless prints a read-only diff of the workflow and package.json changes, plus the npm trust commands.

• npx go-tokenless apply writes the changes.

• It refuses the unsafe cases above instead of guessing.

Limitations

• The npm side (adding the trusted publisher, deleting the old token) needs the user's npm login with 2FA. Hand those steps to the user.

• Trusted publishing covers GitHub Actions, GitLab.com and CircleCI cloud only.