npm trusted tags: review who can move a release before removing its token

A tag operation no longer has to imply a long-lived npm token

GitHub's September 30 changelog says npm trusted-publishing configurations can now receive permission to manage dist-tags using short-lived OIDC credentials. Previously, it says, a workflow that used trusted publishing could still need a granular access token solely to manage tags after a release or rollback.[1]

A dist-tag is an alias for a package version. The npm command reference says an ordinary npm install selects latest by default; moving that tag can therefore change which version future default installs resolve to.[3] For maintainers of agent tools and other npm packages, the important decision is who may redirect that channel—not just whether a secret disappears from CI.

The preserved feed dates the announcement 30 September 2026 at 21:03:09 UTC, which falls on 1 October in Korea. Its URL uses September 30; a separate rollout-completion time was not established. Treat this as a documented change, not proof that a particular package or client is ready.[1]

Staging-only does not necessarily mean unable to redirect latest

The new Allow npm dist-tag permission defaults off for both new and existing configurations. It is independent of direct publishing, and the announcement explicitly says a staging-only configuration can be granted tag management.[1] A workflow's inability to publish directly is therefore not enough to establish that it cannot redirect an already published version's tag.

This independence concerns authorization for explicit npm dist-tag commands, not every path that can change a tag. The npm command reference says publishing a package sets latest to the published version unless --tag is used—for example, npm publish --tag=beta.[3] Dist-tag OFF alone is therefore not a guarantee that a workflow with direct publishing ON leaves latest unchanged. This is a documentary qualification, not a tested OIDC-specific publishing result.

The authorization rule matters when configurations overlap: GitHub says the incoming OIDC token need match any one configuration with the permission enabled.[1] Our interpretation is disjunctive, not unanimous: if the same identity matches configuration A without tag rights and configuration B with them, A's disabled permission does not cancel B's grant. Review all matching configurations rather than only the one named in your release plan.

The source names one opt-in tag-management permission. It does not establish separate promotion and rollback rights, per-tag restrictions, or a tag-specific human-approval mechanism.[1] Do not assume granting access to update beta prevents the same authorized workflow from moving latest. A separate protected promotion workflow is a possible design choice, not a guarantee supplied by this switch.

Hypothetical example: promote a version, then redirect the channel back

This is a permission-planning example, not an executed npm workflow. Assume an agent-tool package already has published versions 2.4.0 and 2.4.1. The intended policy gives a build workflow staging access without direct publishing or tag management; a separately approved promotion workflow may move latest.

The design loses its intended boundary if the build identity also matches a tag-enabled connection. Separating filenames or environment conditions is useful only when the actual incoming identity matches the intended configuration and does not match an unintended enabled one. The official GitHub Actions setup uses organization/user, repository, workflow filename and an optional environment; it requires id-token: write for OIDC.[2] Those setup instructions are not proof of this example's tag behavior.

Use the dist-tag prerequisite, not the older general publishing floor

The general trusted-publishing note requires npm CLI 11.5.1 or later and Node 22.14.0 or higher. A separate dist-tag note is more specific: “dist-tags with OIDC Trusted publishing requires npm CLI version 11.21.0 (or later) and 12.2.0 (or later).”[2] Keep that branch-specific wording visible rather than treating every client above 11.5.1 as compatible. Check which documented threshold applies to the installed CLI branch and its Node requirements.

The docs list GitHub-hosted Actions runners, GitLab.com shared runners and CircleCI cloud; self-hosted runners are not currently supported.[2] After package and workflow setup, the documented path is to run npm dist-tag commands in that workflow, with the CLI authenticating automatically using the CI provider's OIDC identity.[2] This is a supported-path description, not evidence that your workflow has successfully used it.

Tag permission also matters for reading: the current docs say reading a private package's tags through trusted publishing requires dist-tag permission, while public tags remain readable without authentication.[2] An unauthenticated read of public tags therefore cannot prove that the workflow is authorized to move them. The docs explicitly say npm whoami is not a check of trusted-publishing permissions; verify the operation you intend to perform.[2]

npm does not validate a trusted-publisher configuration when it is saved. The docs' calling-versus-called workflow discussion concerns publishing; we have not established precisely the same matching behavior for tag operations.[2] Inspect the incoming identity and all applicable configurations instead of treating a saved setting or successful publish as proof of tag authority.

Remove only the credential whose job has actually been replaced

The announcement says existing token-based dist-tag management continues unchanged.[1] The official docs separately note that private dependency installation may still require read-only credentials, and stage approval/rejection requires interactive authentication rather than OIDC.[2] This is not an announcement that every release credential can disappear.

Our recommendation is to consider removing a tag-management token only after the maintainer verifies a supported client and runner, the intended OIDC match, all overlapping tag grants, and representative promotion and rollback in an authorized test context. Observe the actual tag target after each permitted operation and check that the build-only identity cannot retag through another grant. Also review publish-time channel selection: the npm command reference says publishing sets latest unless --tag is used.[3] Turning dist-tag OFF is not a substitute for reviewing direct-publishing authority and its selected tag. This is a proposed verification, not a test we performed.

Keep the existing constrained path while client compatibility or the permission boundary remains unresolved. If the documented version conditions and workflow-specific checks establish that OIDC replaces the token's sole job, removing that specific credential becomes a reasonable next decision. The benefit is a possible reduction in persistent credentials; no measured security improvement, time saving or maintainer demand is established here.