go-tokenless

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.

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

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."

{ "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]

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.

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