npm-trusted-publishing - Claude MCP Skill

# npm Trusted Publishing

Moves 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/)).

## 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

| 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

```yaml
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](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.
- `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.