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.
- 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.
- 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+.
- 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.
actions/setup-node has registry-url: https://registry.npmjs.org.
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.
- 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.
- 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
| Error |
Usual cause |
ENEEDAUTH |
No id-token: write, npm older than 11.5.1, or a workflow file name that doesn't match the trusted publisher |
404 Not Found - PUT https://registry.npmjs.org/<pkg> |
Same as above, a mismatched environment, no trusted publisher yet, or an expired token still being used |
E422 ... repository.url |
repository is missing in package.json or names another repo |
| Publish still uses the token |
A token remains in env, .npmrc or .yarnrc.yml (checklist item 3) |
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.
1---2name: npm-trusted-publishing3description: Set up or fix npm trusted publishing (OIDC) in GitHub Actions and remove NPM_TOKEN. Use for ENEEDAUTH, E404 on PUT, E422 repository.url, or migrating off 2FA-bypass tokens before January 2027.4metadata:5 source: https://skillmd.com/skills/github/npm-trusted-publishing6---78# npm Trusted Publishing910Moves a GitHub Actions release from a stored `NPM_TOKEN` to npm [trusted publishing](https://docs.npmjs.com/trusted-publishers). 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](https://docs.npmjs.com/about-access-tokens/)).1112## When to Use This Skill1314- The user wants to remove `NPM_TOKEN` / `NODE_AUTH_TOKEN` from a release workflow or set up OIDC or provenance publishing.15- A CI publish fails with `ENEEDAUTH`, `404 Not Found - PUT https://registry.npmjs.org/...` or `E422 ... repository.url`.16- Release logs show `npm notice npm tokens that bypass 2FA are being restricted`.1718## Checklist (all must hold)1920Work through every item. Missing any one of them produces the errors above.21221. **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.232. **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+.243. **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.254. **`actions/setup-node` has `registry-url: https://registry.npmjs.org`.**265. **`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.276. **A trusted publisher exists on npm for each package** (npmjs.com → package → Settings → Trusted publishing), or with npm 11.15+:28 `npm trust github <pkg> --repo OWNER/REPO --file release.yml --allow-publish --yes`29 - The workflow **file name** must match exactly; it is case-sensitive and includes `.yml`.30 - For a **reusable workflow**, use the *calling* workflow's file name, and grant `id-token: write` in the caller too.31 - If the job uses `environment:`, set the same environment on the publisher.32 - A package that doesn't exist yet must be published once by hand first.337. **GitHub-hosted runner.** Self-hosted runners can't use trusted publishing.3435## Security Rules3637- **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`.38- **Dry runs:** `npm publish --dry-run` and `npm pack` jobs don't publish, so they need no `id-token` and no trusted publisher.39- **The old token:** delete the secret (`gh secret delete NPM_TOKEN`) and revoke it on npmjs.com only after the first tokenless release succeeds.4041## Error Guide4243| Error | Usual cause |44|---|---|45| `ENEEDAUTH` | No `id-token: write`, npm older than 11.5.1, or a workflow file name that doesn't match the trusted publisher |46| `404 Not Found - PUT https://registry.npmjs.org/<pkg>` | Same as above, a mismatched `environment`, no trusted publisher yet, or an expired token still being used |47| `E422 ... repository.url` | `repository` is missing in `package.json` or names another repo |48| Publish still uses the token | A token remains in env, `.npmrc` or `.yarnrc.yml` (checklist item 3) |4950## Example5152```yaml53jobs:54 publish:55 runs-on: ubuntu-latest56 permissions:57 contents: read58 id-token: write59 steps:60 - uses: actions/checkout@v561 - uses: actions/setup-node@v662 with:63 node-version: 2464 registry-url: https://registry.npmjs.org65 - run: npm ci66 - run: npm publish --access public # no NODE_AUTH_TOKEN67```6869## Automating It7071[go-tokenless](https://github.com/Continuous-Actions/go-tokenless) (MIT) applies this checklist to an existing repository. Use it when the user wants the edits made for them.72- `npx go-tokenless` prints a read-only diff of the workflow and `package.json` changes, plus the `npm trust` commands.73- `npx go-tokenless apply` writes the changes.74- It refuses the unsafe cases above instead of guessing.7576## Limitations7778- 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.79- Trusted publishing covers GitHub Actions, GitLab.com and CircleCI cloud only.