trusted-publish-check

trusted-publish-check

Catches npm OIDC trusted-publishing misconfig before it breaks your release.

npm retired classic publish tokens (creation disabled 2025-11-05, all revoked ~2025-12-09), so most CI publish workflows have moved to trusted publishing — no token, just a GitHub Actions OIDC identity. The setup is a handful of small, exact-match requirements, and npm doesn't validate any of them when you save the config. It only checks at publish time, and when it's wrong you get a bare 404 or ENEEDAUTH with no indication of which of the ~6 things is broken (npm/cli#9088).

trusted-publish-check reads your .github/workflows/*.yml and package.json and tells you which one it is, before you push.

$ npx trusted-publish-check

trusted-publish-check  scanned 1 workflow file(s) in .

  [will-fail] Job 'publish' in publish.yml is missing 'id-token: write'
    Without id-token: write, the runner cannot mint the OIDC token trusted publishing needs.
    npm falls back to a token auth path with no token configured, surfacing as 404/ENEEDAUTH.
    - no permissions block found at job or workflow level
    fix: Add to job 'publish' (or the workflow top level):
      permissions:
        id-token: write
        contents: read

  1 likely publish failure(s), 0 thing(s) to double-check. Your next npm publish will likely 404/ENEEDAUTH.

Install

No install needed — run it with npx:

npx trusted-publish-check

Or add it to your publish workflow so a bad config fails the PR, not the release:

- run: npx trusted-publish-check

What it checks

All static, all read-only, no network calls:

• Reusable-workflow indirection — your publish job lives behind workflow_call. npm validates the filename of the calling workflow, not the one that actually runs npm publish.
• Missing permissions: id-token: write on the job that publishes, without which the runner never mints an OIDC token at all.
• NODE_AUTH_TOKEN set on the publish step — even to an empty string. npm tries the token auth path first and never falls through to OIDC.
• npm/Node pinned below the OIDC minimum. Trusted publishing needs npm ≥ 11.5.1 and Node ≥ 22.14.0; an unpinned or old setup-node silently leaves you on a CLI that doesn't speak OIDC.
• Scoped package with no public access. @scope/name publishes private by default — the first publish 404s exactly like a broken trusted-publisher config, with no other symptom to distinguish the two.
• More than one workflow file that can run npm publish — npm doesn't verify the filename you configure on npmjs.com when you save it, so an ambiguous setup fails silently at the worst time.

Usage

trusted-publish-check [path]     Scan a repo (default: current directory)

Options:
  --json         Machine-readable output
  --warn-only    Always exit 0 (report without blocking)
  -h, --help     Show this help

Exit code 1 on any finding likely to break your next publish, 0 otherwise (or always with --warn-only, if you'd rather report than gate).

What it doesn't do

It's a preflight linter, not a publish gate or a security scanner — it doesn't touch your registry config, doesn't need any credentials, and doesn't attest or sign anything. It just reads your workflow files and tells you what npm's trusted-publisher validation is about to reject.

License

MIT

Built autonomously by an AI agent as part of an experiment in AI-run software ventures.