To configure npm trusted publishing, open the package settings on npmjs.com, add a trusted publisher with your GitHub owner, repository and exact workflow filename, grant the job id-token write, and use npm CLI 11.5.1 or later. Errors usually come from a mismatched name, an old CLI or an unused configuration.
Requirements
Per npm's documentation:
- npm CLI 11.5.1 or later and Node 22.14.0 or later.
- A supported provider on cloud hosted runners: GitHub Actions, GitLab CI/CD or CircleCI. Self hosted runners are not supported.
- For GitHub Actions, id-token write permission in the workflow.
- The repository URL in package.json must exactly match the GitHub repository.
Setup steps for GitHub Actions
- Open the package on npmjs.com, go to Settings, then Trusted publishing.
- Enter the GitHub user or organization, the repository, and the workflow filename. Use the filename only, including the .yml or .yaml extension. The file must be in
.github/workflows/. - Optionally enter an environment name, and make the workflow use the same one.
- In the workflow, add
id-token: writeto the publish job. - Publish from that workflow.
You can add up to 10 trusted publishers per package. Existing connections cannot be edited; delete and recreate them.
Two traps in the documentation
npm does not validate the configuration when you save it, so a typo appears only when you publish. And a new configuration must complete its first successful publish within 2 days or it expires. Plan to do the setup and a test release together.
Troubleshooting table
| Symptom | Likely cause |
|---|---|
| Publish falls back to asking for a token | Workflow filename, owner or repo does not match the saved publisher |
| Provenance missing | Private repository, or a provider that does not generate it |
| Works locally, fails in CI | CLI older than 11.5.1, or Node older than 22.14.0 |
| Fails on a self hosted runner | Not supported |
| Configuration stopped working after days | It was not used within 2 days of creation |
| Repository mismatch error | package.json repository url differs from the GitHub repository |
| Environment mismatch | Workflow environment name does not equal the saved one |
Print the CLI and Node versions at the top of the job. It saves a lot of guessing.
What it covers and does not
Trusted publishing covers publishing. It does not cover npm install, so use a read only granular token for private dependencies. Dist tag management is off by default and needs a newer CLI and an explicit allowance in settings. Provenance is generated automatically for public packages from public GitHub or GitLab repositories, and not for CircleCI or private repositories.
Lock the door behind you
After the first successful publish:
- Set the package to require 2FA and disallow tokens. See what the disallow tokens setting does.
- Revoke old tokens.
- Protect the workflow file with CODEOWNERS.
- Consider staged publishing so a maintainer approves each release.
- Compare approaches in npm versus PyPI trusted publishing.
Safeguard scans the dependencies you publish with and generates SBOMs; the free scan is at gold.safeguard.sh/scan.
Quick check
Does the workflow filename include the folder?
No. Enter the filename only, with its extension. The file lives in the workflows folder.
Can I use trusted publishing from a self hosted runner?
Not according to npm's documentation, which supports cloud hosted runners only.
Sources
Last reviewed: 19 October 2026.
