npm Trusted Publishing Removes Long-Lived Tokens. Here Is the GitHub Actions Setup Checklist
A practical npm Trusted Publishing and OIDC guide for package maintainers covering GitHub Actions setup, provenance, token removal, permissions, and migration safety.
In This Article
Why npm Trusted Publishing Matters Now
npm Trusted Publishing lets supported CI/CD systems publish packages with OpenID Connect instead of long-lived npm automation tokens. For maintainers, the practical benefit is simple: there is no reusable publish token sitting in GitHub secrets waiting to be leaked, copied, or forgotten.
This is now a high-interest JavaScript supply chain topic because package publishing credentials are powerful. If a token can publish your package, an attacker who steals it can publish your package too. OIDC trusted publishing narrows that risk by issuing short-lived credentials to an approved workflow.
What You Need Before You Start
npm's docs say Trusted Publishing requires npm CLI 11.5.1 or later and Node 22.14.0 or higher. You also need package publish permissions on npm, a supported CI/CD provider, and a workflow that is specific enough to trust.
For GitHub Actions, the workflow needs id-token: write permission so GitHub can mint an OIDC token. It also needs contents: read and the normal setup steps for checkout, Node, install, build, test, and npm publish.
Configure the Trusted Publisher on npm
Start on npmjs.com, not in the workflow file. Open the package settings, add a trusted publisher, and choose the provider, repository, workflow file, and environment or branch constraints that match your release process.
Be precise. A broad workflow that can run from many branches is easier to misuse. A release workflow triggered by version tags, protected branches, or reviewed environments is usually easier to reason about. For monorepos, configure each package intentionally instead of assuming one setting covers every release path.
Use a Minimal GitHub Actions Publish Workflow
The core GitHub Actions pattern is: check out the repository, set up Node with the npm registry URL, install clean dependencies, run the build, run tests, and publish. The key security line is permissions: id-token: write.
Avoid caching in release builds unless you have a clear reason and trust boundary. Keep release scripts boring. Do not run unreviewed pull request code in a publish-capable workflow. Do not put broad cloud credentials, npm tokens, or unrelated deployment secrets in the same job.
Provenance Is Helpful, Not Magic
npm says trusted publishing can automatically generate provenance attestations for public packages published from public repositories through supported providers. Provenance helps users see where and how a package was built.
But provenance does not prove the code is safe. It proves build origin and process metadata. A compromised workflow, unsafe release trigger, poisoned dependency, or malicious maintainer can still produce a package with provenance. Treat provenance as evidence, not a guarantee.
Migration Checklist From npm Tokens
Set up Trusted Publishing first. Run a test release on a low-risk package or prerelease tag. Confirm the package publishes, provenance appears where expected, and consumers can install it. Then restrict token access, revoke old automation tokens, and remove NPM_TOKEN secrets from repositories that no longer need them.
Finally, document the release path. Include who can approve releases, which workflow publishes, what branch or tag triggers it, where provenance is checked, and what to do if a release fails. Tokenless publishing is strongest when the workflow is narrow, reviewed, and easy to audit.