# Stage-Only npm Tokens Put Release Approval Back In The Pipeline

- Link: https://thestackobserver.com/stage-only-npm-tokens-put-release-approval-back-in-the-pipeline/
- Published: 2026-09-21T15:33:08-04:00
- Author: Stackxx

GitHub’s new stage-only npm tokens are a small-looking change with a large operational
message: the JavaScript publishing pipeline is moving away from unattended direct
release rights and toward a two-step release boundary that CI can prepare but a 
human, protected by two-factor authentication, must approve.

The immediate feature is straightforward. npm granular access tokens can now be 
created with **Read and write (stage only)** permissions. A workflow using that 
token can submit a package version with `npm stage publish`, but npm rejects a direct`
npm publish` attempt with the same credential. A package maintainer then reviews
and approves the staged version with 2FA. GitHub says the option is available for
existing npm packages, requires publish access, requires 2FA on the npm account,
and depends on npm CLI 11.15.0 or later and Node.js 22.14.0 or later.

That matters because npm is also targeting January 2027 to remove direct publishing
through bypass-2FA tokens. For platform teams, this is not simply another registry
permission to document. It is a deadline for separating build automation from release
authority, and for finding every CI job, bot account, composite action, release 
script, and local maintainer workflow that still assumes a token can publish straight
to the registry.

## The Operational Problem Is Bigger Than One Token Type

Most mature engineering organizations already know they should reduce long-lived
package publishing credentials. The hard part is that publishing pipelines tend 
to accrete quietly. A package that began with a single maintainer’s laptop becomes
a GitHub Actions workflow. The workflow receives a token. A monorepo release tool
starts publishing several workspaces at once. A bot starts moving dist-tags. A rollback
script gets its own credential. After a few years, nobody has a complete map of 
which credentials can actually put code in front of downstream consumers.

Stage-only tokens force that map into the open. They preserve enough write access
for automation to prepare a release, but they remove the most dangerous step from
the unattended path: making a new package version immediately installable from the
public registry. That distinction is valuable after a supply-chain incident because
it limits what an exposed CI secret can do without also compromising a maintainer
approval path.

The feature does not eliminate risk. GitHub notes that stage-only tokens retain 
other package write permissions, including moving dist-tags and deprecating versions,
so they still deserve the same handling as other write credentials. A stolen stage-
only token may not publish a new version directly, but it can still create disruption
or be paired with other weaknesses. The practical win is narrower and still important:
the release path gains a review point where a maintainer can inspect the staged 
artifact before it becomes the version consumers receive.

## Why CI Direct Publishing Became The Wrong Default

Direct publishing from CI made sense when teams optimized mostly for release speed
and repeatability. A clean tag, a passing workflow, and a registry token could produce
a package release in seconds. For internal packages or low-risk libraries, that 
convenience was compelling. For public packages with broad dependency reach, it 
has become an increasingly uncomfortable default.

Recent npm compromises show why. Cloudsmith’s August write-up on compromised `keyv`
and `cacheable` packages described a campaign in which malicious versions were pushed
to legitimate packages and delivered through install-time lifecycle scripts. The
important platform lesson was not only that individual packages were affected. It
was that legitimate publishing rights, once stolen, can become distribution infrastructure.
In that kind of incident, release automation is part of the blast radius, not just
a deployment convenience.

Cloudsmith’s broader guidance on trusted supply chains makes the same point from
another direction: organizations need controlled points where packages are inspected,
governed, and allowed to move toward production. For consumers, that may mean curated
repositories, cooldown policies, malware detection, and artifact promotion flows.
For publishers, the equivalent control is staged release authority. A build may 
produce and submit a package, but publishing should become a governed act with identity,
review, and auditability around it.

That is the core thesis platform teams should take from GitHub’s change. npm publishing
is becoming less like a background CI side effect and more like a deployment control
plane. Treating it that way will make the January 2027 transition far less painful.

## Inventory The Paths That Can Publish

The first practical task is discovery. Teams should not begin by swapping token 
scopes in the most visible workflow and assuming the job is done. Start with a publishing
inventory that records package name, registry, workflow location, token owner, token
type, 2FA posture, release trigger, dist-tag behavior, and rollback procedure.

For GitHub-hosted projects, search workflow files for `npm publish`, `npm access
token` references, registry authentication setup, release tooling such as changesets
or semantic-release, and package manager commands that wrap publishing. Also inspect
composite actions and reusable workflows, because many organizations centralized
publish logic there and then forgot how many repositories consume it. For monorepos,
map whether one pipeline publishes every package or whether individual packages 
have separate release jobs.

Do the same outside GitHub Actions. Jenkins jobs, CircleCI projects, Buildkite pipelines,
self-hosted runners, release manager laptops, and containerized publishing utilities
often keep their own credentials. If the organization has been through mergers or
team restructures, stale publish paths may exist in places nobody checks during 
normal development.

The output should be a living register, not a spreadsheet created only for migration
week. Any credential capable of changing package state belongs in the same operational
view as deployment keys and production cloud roles. That includes direct publishing
tokens today, stage-only tokens tomorrow, and any trusted publishing identity the
team adopts later.

## Redesign The Release Flow Around Staging

Once the current state is visible, the release process can be redesigned. A strong
staged publishing workflow usually has four distinct moments: build, submit, review,
and release. CI builds from a trusted source revision, runs tests and provenance
steps, and creates the package artifact. The stage-only token submits that artifact
with `npm stage publish`. A maintainer reviews the staged version, checks metadata
and changelog content, and approves the release with 2FA. Post-release automation
then verifies the registry state, announces the release, and updates dependent systems.

That separation changes the shape of CI permissions. The workflow that builds and
stages a package no longer needs permission to complete the release. The person 
or protected identity that approves the release does not need to hold a reusable
publish token in CI. Review becomes a deliberate checkpoint rather than an informal
glance at a workflow log after the package has already shipped.

Teams should decide which releases require human approval and which can move to 
trusted publishing instead. GitHub positions stage-only tokens as a migration path
for teams that cannot yet move to trusted publishing. That distinction matters. 
Stage-only tokens are useful, especially for existing automation that needs a near-
term replacement for bypass-2FA direct publishing. They are not necessarily the 
end state for every package. Where trusted publishing is available and fits the 
team’s registry, identity provider, and workflow design, it may remove more long-
lived secret exposure than a token-based staged path.

## Define What Maintainers Must Review

A staged release is only as useful as the review behind it. Platform teams should
give maintainers a short, repeatable checklist so approval does not become a rubber
stamp under time pressure.

 * Confirm the package name, version, and dist-tag match the intended release plan.
 * Review the generated package contents, not only the repository diff. Published
   packages often include build output, generated files, and metadata that do not
   appear clearly in source review.
 * Check dependency and script changes, especially install-time lifecycle scripts
   and postinstall behavior.
 * Verify that provenance, signature, or build attestation steps completed as expected
   where the package supports them.
 * Confirm that the staged artifact came from the expected commit and release workflow.

The checklist should be embedded in the release tool or pull request template, not
left in a wiki page that maintainers rarely open. If the team uses a developer portal
or internal service catalog, package ownership metadata should point directly to
the release approvers. If a maintainer is unavailable, the fallback approver should
be explicit before a release is urgent.

## Protect The New Token Like A Write Credential

It is tempting to treat stage-only tokens as low-risk because they cannot directly
publish new versions. That would be a mistake. GitHub explicitly warns that they
retain other write permissions, including dist-tag movement and deprecation rights.
Those powers can affect consumers, break installs, or hide malicious activity during
an incident.

Use the same controls expected for sensitive release credentials. Scope each token
to the minimum set of packages. Store it only in the CI secret manager or protected
automation environment that needs it. Rotate it during migration and after any runner
compromise. Ensure logs cannot print it. Restrict who can modify workflows that 
consume it. Prefer environment protections for release workflows so a pull request
cannot quietly alter the publish path and exfiltrate the credential.

Also review runner trust. A stage-only token is still exposed to the machine that
runs the staging workflow. If untrusted pull request code can execute in that environment,
the credential boundary is already broken. The migration to staged publishing is
a good time to separate build validation jobs from release jobs, require protected
branches or signed tags for release triggers, and make sure package staging runs
only from trusted code.

## Plan For January 2027 Now

The January 2027 target gives teams enough time to avoid a rushed registry outage,
but only if they start before release freezes and year-end planning compress the
calendar. A sensible migration plan begins with the highest-impact packages: public
packages, packages with many internal dependents, packages that publish from long-
lived bot tokens, and packages owned by teams with frequent releases.

For each package, choose one of three paths. Move to trusted publishing where the
workflow can support it. Move to stage-only tokens where token-based automation 
is still required. Retire or disable publishing paths that are no longer used. The
third option is easy to overlook and often produces the quickest risk reduction.

Then run at least one real release through the new path before the old token model
disappears. Dry runs help, but publishing systems fail in details: package manager
versions, Node.js versions, 2FA account posture, maintainer permissions, dist-tag
assumptions, release notes generation, and post-release verification. GitHub’s requirements
for staged publishing include npm CLI 11.15.0 or later and Node.js 22.14.0 or later,
so base images and setup actions may need to change before the token change itself
can work.

## What To Watch

The main tradeoff is release latency. Staged publishing adds an approval step, and
that can frustrate teams accustomed to fully automated releases. The answer is not
to bypass the control, but to make approval fast and observable. Maintainers should
receive a clear notification, a concise diff of the packaged artifact, and an obvious
approval path. Service-level expectations for routine patch releases may need to
be documented, especially for packages that support incident response.

Another watch item is dist-tag governance. Because stage-only tokens retain dist-
tag permissions, teams should decide whether the staging workflow is allowed to 
move tags or whether that should happen only after approval. Many consumers install
from tags rather than exact versions, so tag movement deserves almost the same attention
as publishing.

Finally, do not let the migration obscure consumer-side defenses. Staged publishing
reduces one publisher-side risk, but downstream organizations still need lockfiles,
curated registries, cooldown windows, malware detection, and fast credential rotation
procedures. The healthiest supply-chain posture assumes that some upstream publisher
will still be compromised and asks whether the consuming environment can absorb 
that event without immediate execution.

## The Platform Team Takeaway

GitHub’s stage-only npm tokens are a practical bridge between old token-based publishing
and a stricter release model. The organizations that benefit most will be the ones
that use the change to redesign release authority, not merely to rename a secret.

By January 2027, direct publishing through bypass-2FA tokens is expected to disappear.
Between now and then, platform teams should inventory publishing paths, remove stale
credentials, adopt staged or trusted publishing where appropriate, and make maintainer
approval a visible part of the release workflow. The goal is not ceremony for its
own sake. The goal is to make sure a compromised automation token cannot silently
become the next public package release.

## Sources

 * [GitHub Changelog: Stage-only npm tokens for safer automation](https://github.blog/changelog/2026-09-18-stage-only-npm-tokens-for-safer-automation/)
 * [Cloudsmith: Keyv and Cacheable npm Packages Compromised in Active Supply-Chain Attack](https://cloudsmith.com/blog/keyv-and-cacheable-npm-packages-compromised-in-active-supply-chain-attack)
 * [Cloudsmith: Trust your software supply chain from ingestion to production](https://cloudsmith.com/blog/trust-your-software-supply-chain-from-ingestion-to-production)