npm Trusted Publishing Adds OIDC Dist-Tag Permissions for Token-Free Release Pipelines

What changed​

GitHub's changelog describes the change in a few points:

• New per-configuration setting. Each trusted publishing configuration now has an Allow npm dist-tag permission. It can authorize tag operations such as promoting a version to latest or updating next and beta pointers.
• Off by default everywhere. GitHub says the permission starts disabled for both new and existing configurations, so no configuration gains new powers automatically.
• Separate from publishing. The permission doesn't depend on direct publishing rights, so a staging-only configuration can also be allowed to manage tags. It also works the other way: permission to publish or stage does not include tag management.
• Any matching configuration authorizes. A dist-tag operation succeeds if the incoming OIDC token matches any one configuration that has the permission turned on.
• Tokens still work. Existing token-based dist-tag management keeps working unchanged.

The daily.dev summary of the changelog agrees: the new 'Allow npm dist-tag' setting defaults to off for all configurations, is independent of publish permissions, and existing token-based dist-tag workflows continue to work unchanged.

Summary: This adds a narrow permission. Nothing is granted until you enable it on a specific configuration.

Why maintainers were asking for it​

Trusted publishing lets a CI job prove its identity to npm with OIDC instead of storing a secret. npm's documentation says trusted publishing allows you to publish npm packages directly from your CI/CD workflows using OpenID Connect (OIDC) authentication, eliminating the need for long-lived npm tokens. Before this change, that covered npm publish and npm stage publish, but not npm dist-tag.

You could see the gap in real projects. In a GitHub issue from late September, the maintainers of the robota project planned their move to OIDC and noted that OIDC authenticates npm publish / npm stage publish only. npm dist-tag, npm whoami, npm deprecate do not work with it. Their fix was to plan on dropping the beta dist-tag sync (npm dist-tag add <pkg>@<ver> beta --otp): unsupported under OIDC. In other words, a release channel was going to be removed because the security model couldn't support it.

npm's own community discussion shows the same pressure. On September 3, 2026, npm launched support for multiple trusted publishing configurations and asked maintainers what still forced them to keep long-lived tokens. One maintainer replied that managing dist-tags still needed a long-lived token and pointed to an npm CLI issue that had been open for more than a year. Another said that after recent changes to 2FA-bypass granular access tokens, removing pull-request preview tags from CI had become impossible without interactive 2FA. On September 17, npm maintainer Leo Balter replied that opt-in dist-tag support for trusted publishing configurations was coming soon. The September 30 changelog is that feature shipping.

Summary: This is a response to specific, documented complaints, especially about promoting releases and cleaning up PR tags from CI.

How to enable it​

Here is the procedure based on GitHub's changelog and npm's trusted publishing documentation:

1. Find the right configuration. On npmjs.com, go to your package's settings and open the trusted publishing section. npm's docs say each package can have up to 10 trusted publisher connections, for example separate stable, prerelease and staging workflows.
2. Enable Allow npm dist-tag only where it's needed. Pick the configurations whose workflows actually move or remove tags. Leave it off everywhere else.
3. Check the CI side. On GitHub Actions, the workflow must have id-token: write. npm's example workflow marks it Required for OIDC. GitLab needs an id_tokens entry with the audience npm:registry.npmjs.org. CircleCI passes an OIDC token in NPM_ID_TOKEN.
4. Use standard npm CLI commands in the job, for example:
   • npm dist-tag add [email][email protected][/email] next adds or moves a tag
   • npm dist-tag rm example-package beta removes a tag
   • npm dist-tag ls example-package shows the current tags
5. Test with the real operation. npm says it doesn't validate a trusted publisher configuration when you save it. Mistakes only show up when the workflow tries to act, so run the tag command you actually need in a test run instead of assuming the setup is correct.

Some cautions:

• CLI version. npm's docs say trusted publishing requires npm CLI version 11.5.1 or later and Node version 22.14.0 or higher. The changelog doesn't give a separate minimum version for dist-tag over OIDC. Since this is a new capability, use a current npm CLI in release jobs and check npm's documentation if a tag command fails to authenticate.
• Editing existing configurations. npm's docs say the provider and required identity fields of an existing connection can't be changed; to change them, you delete the connection and create a new one. The changelog says to enable the dist-tag toggle on your configurations, so an allowed-action toggle looks separate from those fixed identity fields. If your settings page doesn't show the toggle on an older connection, recreate that connection.
• Supported runners. npm currently supports GitHub-hosted runners, GitLab.com shared runners and CircleCI cloud. Self-hosted runners aren't supported yet.

Summary: Enable the permission on specific configurations, confirm the OIDC plumbing, and test with the real tag command before retiring any tokens.

The security trade-off​

It's easy to treat anything token-free as automatically safer. It usually is, with caveats.

What's better. A long-lived granular token in CI can leak through logs, a compromised dependency or a careless fork. OIDC credentials are short-lived and tied to a specific repository and workflow. Removing the last token from a release pipeline also means you can use npm's recommended package setting, "Require two-factor authentication and disallow tokens", without losing tag automation.

What still needs care. Moving latest is a powerful action because it decides what most users get from a plain npm install. My own analysis, not a statement from npm: a compromised workflow with this permission could point latest at an older, already-published version, such as one with a known vulnerability, without publishing anything new. The contributors behind a recent autonomys pull request made a related point about OIDC in general. After removing a stored token, they noted that what's left is code running during an approved release: every step in the job can request an OIDC token, including dependency install and build scripts. Removing the token doesn't reduce what the job's own code can do.

Configurations add up. npm's September 3 announcement says configurations only add permissions. None can restrict another, there are no deny rules, and one match is enough. When you audit a package, you have to review every configuration with dist-tag enabled, because any of them is enough to move a tag.

Practical least-privilege steps:

• Put tag operations in a separate job or workflow and enable the permission only on that configuration.
• Use GitHub environments with required reviewers for jobs that promote latest.
• Consider keeping publishing staging-only, which npm recommends because it adds a human 2FA approval before a version goes live. Since the dist-tag permission is independent, a staging-only configuration can still handle tag cleanup.

Summary: Short-lived credentials remove the risk of a stolen token. They don't protect against a trusted workflow that has been made to do the wrong thing.

What it doesn't cover​

This isn't the end of every npm token in CI. npm's documentation says OIDC doesn't handle installs, so projects with private dependencies still need a read-only token for npm ci. The robota notes also list npm whoami and npm deprecate as outside OIDC. The changelog doesn't say deprecation has changed, so projects that automate deprecating old prerelease versions should assume they still need a token. Staged-publishing approvals still require interactive 2FA by design, and this permission doesn't change that.

Bottom line​

For maintainers who were a single npm dist-tag command away from a fully token-free pipeline, this closes the gap. It's opt-in, scoped to individual configurations and doesn't break anything that exists today. Before you revoke your last automation token, audit which configurations can move latest, keep that list as short as possible, and test the exact tag commands your release process runs.