go-tokenless

Delete your NPM_TOKEN. One command switches npm publishing in GitHub Actions to trusted publishing (OIDC). No long-lived token is stored anywhere, and every release gets a provenance badge.

npm is retiring token publishing: from January 2027 a token can no longer publish on its own (npm docs).

Contents

• Quick start
• What it changes
• Supported release setups
• Private packages
• Keep it tokenless in CI
• Use it with AI agents
• Options
• What it accesses
• What only you can do
• Troubleshooting
• Contributing
• License

Quick start

From the root of the repository that publishes to npm:

npx go-tokenless          # 1. preview: lists every change and shows a diff, writes nothing
npx go-tokenless apply    # 2. edit the workflow and package.json files

Then follow the Next steps it prints: commit the change, connect the package to the workflow on npm, and delete the old secret. Needs Node 22.14+.

What it changes

Only the lines that need to change are touched: comments, quoting and layout in your workflows are kept, and in package.json only the repository field is edited. Before writing, go-tokenless re-reads both versions and refuses if anything other than the migration would change.

| Problem in your release workflow | What go-tokenless does | |---|---| | NODE_AUTH_TOKEN / NPM_TOKEN on the publish job (or the workflow) | Removes it, so the secret can be deleted. npm prefers OIDC but falls back to a configured token, which would keep the old token in use | | Job can't request an OIDC token | Adds permissions: id-token: write, keeping the permissions it had | | npm older than 11.5.1 (Node 22 and below) | Adds npm install -g npm@^12, or moves Node < 22 to 24 | | actions/setup-node without registry-url | Adds registry-url: https://registry.npmjs.org | | JS-DevTools/npm-publish below v4 | Updates it to v4, which no longer requires a token | | A script writes _authToken to .npmrc | Removes those lines | | repository missing or in the wrong form in package.json | Sets git+https://github.com/<owner>/<repo>.git (with directory in monorepos) |

It stops with exit code 1 and writes nothing when a person needs to decide:

• Publishing reachable by outsiders: a publish job in a workflow started by pull_request_target, issue_comment, workflow_run and similar triggers. Granting it OIDC would let a fork publish.
• Self-hosted runners, which npm doesn't accept for trusted publishing.
• repository pointing at another repo.
• YAML anchors. Edits could leak into other jobs.
• A hidden publish command: an npm token is passed but the publish command can't be found.

Dry runs (npm publish --dry-run) never count as publishing. Steps that publish to GitHub Packages, and GITHUB_TOKEN values, are left alone.

$ npx go-tokenless
go-tokenless: Ready to go tokenless. (acme/widgets)

Changes:
  .github/workflows/release.yml
    - publish: remove `NODE_AUTH_TOKEN` from job env
    - publish: grant `id-token: write`
    - publish: raise setup-node from Node 20 to 24 (trusted publishing needs Node 22.14+)
  package.json
    - widgets: add repository.url git+https://github.com/acme/widgets.git

Next:
  1. Run `npx go-tokenless apply` (or apply the diff above) and commit the changes on a branch.
  2. Add a trusted publisher for each package. With npm 11.15+ logged in with 2FA, run:
       npm trust github widgets --repo acme/widgets --file release.yml --allow-publish --yes
  3. Merge, then let the release workflow publish once. Check the new version shows a provenance badge.
  4. Delete the old publish token secret (`gh secret delete NPM_TOKEN`) and revoke the token on npmjs.com.

Supported release setups

| Setup | Notes | |---|---| | npm publish (incl. workspaces) | | | pnpm publish / -r publish | pnpm 10 hands off to npm; pnpm 11 needs 11.1.3+ | | Yarn Berry yarn npm publish | Yarn 4.10.3+; remove npmAuthToken from .yarnrc.yml | | changesets (changesets/action) | Works as is; if the first tokenless release can't authenticate, update to v2 | | semantic-release | Needs @semantic-release/npm 13.1.0+ (semantic-release 25+) | | release-please + npm publish | | | Lerna / Nx release | Lerna 9+ | | JS-DevTools/npm-publish | Updated to v4 | | release-it | Also set npm.skipChecks: true | | Reusable workflows (workflow_call) | npm checks the calling workflow's file name; a trust command is printed for every caller | | Publishing inside scripts | Follows package.json scripts, ./scripts/*.sh, make <target> and local composite actions (uses: ./.github/actions/...), including working-directory | | Yarn 1 yarn publish, bun publish | Flagged: those tools can't use trusted publishing yet, so switch to npm publish |

Private packages

If your installs need private packages from your npm org, give the install steps a read-only token. Publish steps stay token-free:

npx go-tokenless apply --read-token NPM_READ_TOKEN

       - run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}
       - run: npm publish

Every install step in the release workflow gets it, including separate build and test jobs. Create a granular token on npmjs.com with read-only access to your packages and save it with gh secret set NPM_READ_TOKEN.

Keep it tokenless in CI

Add the Action to CI. It fails the job if a token creeps back into a publish workflow, and the job summary lists the exact fixes:

# .github/workflows/ci.yml
jobs:
  tokenless:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
      - uses: continuous-actions/go-tokenless@v1
        # with:
        #   mode: report               # annotate only, never fail
        #   read-token: NPM_READ_TOKEN # if installs use a read-only token

It runs go-tokenless --json read-only and needs no token. Its status output is already-tokenless, ready, blocked or no-publish-workflow.

Use it with AI agents

go-tokenless is built to be run by coding agents: --json output, clear exit codes, an MCP server and an Agent Skill. Ask your agent: "Move our npm publishing to trusted publishing."

| Client | Setup | |---|---| | Claude directory (claude.ai, Cowork, Claude Code) | Submitted to Anthropic's plugin directory and awaiting approval. Once listed: open the directory, search go-tokenless and select Add. It then syncs to Claude Code as go-tokenless@synced. Until then, use the marketplace command below | | Claude Code (plugin: skill + MCP) | /plugin marketplace add continuous-actions/go-tokenless then /plugin install go-tokenless@continuous-actions | | Claude Code (MCP only) | claude mcp add go-tokenless -- npx -y go-tokenless mcp | | Gemini CLI | gemini extensions install https://github.com/continuous-actions/go-tokenless | | Cursor, VS Code, others | Add the MCP config below | | Any agent with skills | npx skills add continuous-actions/go-tokenless |

{ "mcpServers": { "go-tokenless": { "command": "npx", "args": ["-y", "go-tokenless", "mcp"] } } }

MCP tools: plan_trusted_publishing (read-only) and apply_trusted_publishing (writes files; no git or network writes). It is listed in the MCP Registry as io.github.continuous-actions/go-tokenless. See also llms.txt and the Agent Skill.

Options

npx go-tokenless [plan | apply | mcp] [options]

| Option | Description | |---|---| | --json | Print the full plan as JSON (status, changes, diff, findings, trust, nextSteps) | | --diff | Include the diff in text output (always on for plan) | | --repo <owner/repo> | GitHub repository, when origin isn't GitHub | | --cwd <dir> | Repository root (default: current directory) | | --offline | Skip the npm registry check that each package already exists | | --read-token <SECRET> | Give install steps a read-only token from this secret (private packages) | | --npm-version <range> | npm for the inserted upgrade step. Default ^12, pinned to one major so releases don't change under you. Other versions show a warning; below 11.5.1 is refused | | --npm-args "<args>" | Extra arguments for every npm command it generates (upgrade step and npm trust) |

Exit codes: 0 ok · 1 blocked (needs a human fix) · 2 usage error · 3 unexpected error.

What it accesses

• Files: it reads .github/workflows/*.yml, package.json files and related scripts in the repository you point it at. apply and the apply_trusted_publishing MCP tool write only to workflow and package.json files inside that repository. It never follows links out of the repository.
• Network: read-only GET requests to https://registry.npmjs.org/<package> to check that each package already exists (--offline or MCP offline: true turns this off). Nothing else is fetched or sent. There is no telemetry.
• Never: it doesn't run repository code, read secrets or environment tokens, run git commands that change anything, or contact npm or GitHub on your behalf.
• Running it: the Claude Code plugin and the Gemini extension start the MCP server with npx -y go-tokenless@<pinned version> mcp.

What only you can do

go-tokenless never touches your npm account, secrets or git history. After apply:

1. Connect each package to the workflow: run the printed npm trust github … commands (npm 11.15+, asks for 2FA), or go to npmjs.com → package → Settings → Trusted publishing.
2. New packages must be published once by hand first; npm can only connect a package that exists. The plan flags these.
3. Delete the old secret and revoke the token after the first tokenless release.

Troubleshooting

Each error has its own page with causes and fixes: ENEEDAUTH, 404 on PUT, E422 repository.url, still using the token, and the 2FA-bypass notice.

| Error | Usual cause | |---|---| | npm error code ENEEDAUTH | No id-token: write, npm older than 11.5.1, or the workflow file name doesn't match the trusted publisher exactly (case-sensitive, with .yml) | | npm error 404 Not Found - PUT https://registry.npmjs.org/... | Same as above, an environment mismatch, or no trusted publisher yet | | npm error code E422 … repository.url | package.json repository doesn't match the GitHub repo. apply fixes the format | | Publishing still uses the token | Something still sets NODE_AUTH_TOKEN, NPM_TOKEN, an .npmrc _authToken or .yarnrc.yml npmAuthToken. Run npx go-tokenless again to find it |

Contributing

Issues and pull requests are welcome. Run corepack enable && yarn install && yarn check (typecheck, build and end-to-end tests). See AGENTS.md for how the code is laid out, and SECURITY.md to report a vulnerability.

License

MIT © continuous-actions