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.
