# npm Trusted Publishing Explained: OIDC, Provenance, Limits

> How npm trusted publishing works: short-lived OIDC instead of npm tokens, automatic provenance, setup fields, requirements, and what it does not stop.

Source: https://playciso.com/blog/npm-trusted-publishing-explained · Published: 2026-11-03 · Publisher: PlayCISO (https://playciso.com)

---

**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 .yml or .yaml extension, 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) ItemWhat the docs say CI providersGitHub Actions, GitLab CI/CD, CircleCI on cloud-hosted runners; self-hosted runners not yet supported Versionsnpm CLI 11.5.1 or later, Node 22.14.0 or later ProvenanceAutomatic for GitHub Actions and GitLab with public repository and package; not for CircleCI or private repositories; disable with `provenance=false` Per packageUp to 10 trusted publishers; an existing connection cannot be edited, delete and recreate it First publishA new configuration must complete its first successful publish within 2 days or it expires Validationnpm 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 workflowsValidation checks the calling workflow; both parent and child need `id-token: write` InstallingNot 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](/blog/litellm-supply-chain-attack-teampcp-what-to-do). 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 - npm Docs: Trusted publishing for npm packages _Educational guidance, not legal advice. Confirm requirements against the npm docs before changing production pipelines._