npm Trusted Publishing Explained: OIDC, Provenance, Limits
TL;DR · the short version
npm trusted publishing lets a CI run publish a package using a short-lived OpenID Connect (OIDC) credential instead of a long-lived npm token, so there is no standing publish secret to steal from CI. The npm docs list GitHub Actions, GitLab CI/CD and CircleCI on cloud-hosted runners (self-hosted runners are not yet supported), and require npm CLI 11.5.1 or later and Node 22.14.0 or later. On npmjs.com you register the organisation or user, repository and workflow filename (plus an optional environment) for each package. Provenance is generated automatically for GitHub Actions and GitLab publishes when the repository and package are public. It does not stop someone who can edit the trusted workflow, or merge to the branch it runs from, from publishing: pair it with branch rules, a protected environment with required reviewers, and a release-integrity review.
npm trusted publishing replaces the long-lived npm token in your CI secrets with a short-lived OpenID Connect (OIDC) credential that only your registered workflow can obtain. If an attacker steals your CI secrets, there is no publish token in them. It is one of the highest-value, lowest-effort supply-chain controls for a JavaScript maintainer, and it has limits you should know before you rely on it.
How it works
- On npmjs.com you register a trusted publisher for the package: for GitHub Actions that is the organisation or user, the repository, the workflow filename (with its
.ymlor.yamlextension, in.github/workflows/), and optionally an environment name. - When the workflow runs, the CI provider issues a short-lived OIDC identity token that names the repository and workflow.
- npm accepts the publish only if that identity matches the registered publisher. No stored token is involved.
- For GitHub Actions and GitLab, npm attaches a provenance statement automatically if the repository and package are public.
Requirements and limits (from the npm docs)
| Item | What the docs say |
|---|---|
| CI providers | GitHub Actions, GitLab CI/CD, CircleCI on cloud-hosted runners; self-hosted runners not yet supported |
| Versions | npm CLI 11.5.1 or later, Node 22.14.0 or later |
| Provenance | Automatic for GitHub Actions and GitLab with public repository and package; not for CircleCI or private repositories; disable with provenance=false |
| Per package | Up to 10 trusted publishers; an existing connection cannot be edited, delete and recreate it |
| First publish | A new configuration must complete its first successful publish within 2 days or it expires |
| Validation | npm does not validate the configuration when you save it; errors show up at publish time |
| Repository URL | repository.url in package.json must exactly match the GitHub repository |
| Reusable workflows | Validation checks the calling workflow; both parent and child need id-token: write |
| Installing | Not intended for npm install; private dependencies still need a read-only token |
Source: npm docs, "Trusted publishing for npm packages". Check it for the current state, since providers and versions are added over time.
Roll-out order that avoids a lockout
- Register the trusted publisher and complete one successful publish with it.
- Set the package's publishing access to require two-factor authentication and disallow tokens (the docs say this does not affect trusted publishers).
- Only then revoke the old automation tokens. This is the same rule as any credential rotation: verify the new path works before the old one dies.
What trusted publishing does not stop
- Someone who can edit the trusted workflow. The identity is "this workflow in this repository", so a malicious change to the workflow publishes with full legitimacy. Protect the workflow file and the branch it runs from with rulesets or branch protection, code owners, and no admin bypass.
- A build from the wrong source. Provenance tells you where a package was built, not that the source was good. Pin the release source and compare tag and artifact; the GitHub Release Integrity Checklist covers this.
- Malicious dependencies. Trusted publishing protects your publishing, not what you import. Scan new versions with the npm Package Scanner.
- An approver who can be phished. Use an environment with required reviewers, and name that environment in the trusted publisher so only approved runs publish.
Why this is in the news
Stolen CI secrets and poisoned releases keep recurring. In the October 2026 LiteLLM compromise, as publicly reported, CI secrets were exfiltrated and a release was built from a fork source; see our LiteLLM write-up. Token-free publishing removes one link in that chain; it does not remove the others.
What security leaders should do this week
- List every package your organisation publishes and whether each still uses a long-lived npm token.
- Move the highest-impact package first, following the roll-out order above.
- Run the release integrity checklist against that package's pipeline and fix the Missing items.
- Audit the workflow with the GitHub Actions Security Auditor.
- See the GitHub security hub for the rest of the toolkit.
FAQ
What is npm trusted publishing?
Publishing from CI with a short-lived OIDC credential tied to a registered repository and workflow, instead of a stored long-lived npm token.
Which CI systems does npm trusted publishing support?
GitHub Actions, GitLab CI/CD and CircleCI on cloud-hosted runners. Self-hosted runners are not yet supported, per the npm docs.
What versions do I need?
npm CLI 11.5.1 or later and Node 22.14.0 or later. Dist-tag management over OIDC needs a newer CLI and the Allow npm dist-tag option, which is off by default.
Does trusted publishing create npm provenance?
For GitHub Actions and GitLab, automatically, when the repository and package are public. Not for CircleCI or private repositories; provenance=false turns it off.
Does trusted publishing stop a supply-chain attack?
It removes the reusable publish token. It does not help if an attacker can change the trusted workflow, merge to its branch or approve the release, so combine it with branch rules, a protected environment and a release-integrity review.
Sources
Educational guidance, not legal advice. Confirm requirements against the npm docs before changing production pipelines.