A package can already use OIDC for publishing yet still retain an access token for post-release tag updates. The dist-tag support announced on September 30, 2026 gives maintainers a way to revisit that remaining credential.

Before removing it, there is a useful question to answer: should permission to publish a new version also mean permission to change which version users receive?

Promoting a version to latest makes the distinction concrete. It also shows where a CI workflow needs its own authorization boundary.

Moving latest changes which published version users receive

A dist-tag names a package version. By default, npm install <package> without a version or tag resolves latest. Names such as next and beta can represent other release channels, but npm assigns no special meaning to tags other than latest. The npm dist-tag reference describes these relationships.

Suppose latest points to 2.0.0 and next points to an already published 2.1.0. After validation, pointing latest to 2.1.0 promotes that same version to the default channel. Changing this reference is a separate operation from publishing the package again.

That distinction matters for authorization. A workflow allowed to change tags can redirect a release channel without creating a new version. Its execution conditions therefore belong in the release process, even when its job is only promotion.

Dist-tag authorization is independent of direct publishing

Trusted publishing previously covered publishing and staging, leaving tag operations outside its scope. The new Allow npm dist-tag permission enables tag management with short-lived OIDC credentials. It defaults to off for both new and existing configurations, while token-based tag management continues to work. GitHub announcement

This permission is independent of direct publishing. A configuration can allow staging and tag management without allowing direct npm publish. Denying direct publication therefore does not necessarily prevent a workflow from changing a release channel.

OIDC presents a token containing workflow identity information, which the receiving service checks against its trust conditions. It reduces the need to store long-lived secrets while leaving the choice of trusted workflows to the operator. GitHub’s OIDC explanation describes this authentication and authorization flow.

With multiple configurations, an operation is authorized when the incoming OIDC token matches any configuration that permits dist-tag management. Consequently, disabling the permission on one overlapping configuration may not prevent access through another. Review all configurations that the promotion workflow could match.

Use a supported CLI and compare tags before and after promotion

The CI client must support the operation as well. The npm trusted publishing guide lists 11.21.0 or later in the 11.x line and 12.2.0 or later in the 12.x line for OIDC dist-tag support. The npm CLI 12.2.0 release notes also record the addition.

An existing OIDC publish succeeding does not establish support for tag operations. Check npm --version inside CI, then enable Allow npm dist-tag on the intended trusted publisher configuration.

The following promotion example runs inside a workflow already configured for OIDC. Replace example-package and 2.1.0 with a package you manage and an already published version. The middle command changes the registry tag.

# Inspect the current tag targets
npm dist-tag ls example-package

# Promote a validated, published version to the default channel
npm dist-tag add [email protected] latest

# Verify that latest points to the intended version
npm dist-tag ls example-package

The syntax follows the npm dist-tag reference. Public package tags are readable without authentication, so successfully listing them does not prove write authorization. Reading private package tags through trusted publishing requires dist-tag permission. Verify the intended operation against these authentication rules.

Separate remaining token uses before retiring the promotion credential

The practical goal is to retire a long-lived credential kept solely for tag updates. Existing tokens still work, so validate the intended tag operation through OIDC before revoking the credential that has become unnecessary.

Other tasks, such as installing private dependencies, may still need token authentication. The npm migration and authentication guide distinguishes those read operations and recommends verifying trusted publishing before revoking unused tokens.

Separating publication from promotion clarifies where permission belongs. Authorize the workflow responsible for promotion, review how it runs, and verify the resulting tag change. Then retire its dedicated tag-management token: fewer credentials to maintain, with responsibility for choosing the release channel still explicit.

Source

• Title: Opt-in dist-tag permissions for npm trusted publishing
• URL: https://github.blog/changelog/2026-09-30-opt-in-dist-tag-permissions-for-npm-trusted-publishing