npm token publishing ends in January 2027: move CI to staged or trusted publishing

npm ends token-based direct publishing in January 2027. Move CI to OIDC trusted publishing or stage-only tokens with 2FA approval before then.

Read time
19 min
Word count
2.9K
Sections
13
FAQs
8
Share
Engineer reading a printed checklist beside a laptop and security key, with npm publishing readiness title text
On this page · 13 sections
  1. What ends in January 2027, and what has already changed
  2. Why the bee-js release changes the advice
  3. Which publish paths survive January 2027
  4. Path A: OIDC trusted publishing on GitHub Actions, GitLab and CircleCI
  5. Path B: stage-only tokens for Jenkins, self-hosted runners and self-managed GitLab
  6. The approval step: who presses the button
  7. Provenance: what you keep, what you lose, what it proves
  8. Decision table
  9. Worked example: a 120-person US and UK SaaS company
  10. US and UK notes
  11. Migration checklist
  12. How eCorpIT can help
  13. References

Summary. npm will remove the ability to publish new package versions directly with a granular access token in January 2027. No exact day has been announced; GitHub's changelog of 8 July 2026 says around January 2027. Treat any CI job that runs npm publish with an NPM_TOKEN secret as broken from 1 January. Two routes remain. OIDC trusted publishing works from GitHub-hosted Actions runners, GitLab.com shared runners and CircleCI cloud, needs npm CLI 11.5.1 and Node 22.14.0 or later, and can still be allowed to publish directly. Everywhere else, including Jenkins and self-hosted runners, a stage-only token runs npm stage publish (npm CLI 11.15.0 or later) and a maintainer approves each version with 2FA. New trusted-publisher configurations expire if unused for 48 hours. The 9 November hijack of @ethersphere/bee-js went out through trusted publishing with genuine provenance and stayed live for about 75 minutes. Our advice: stage-only permission even on OIDC, a stage-only token everywhere else, and a named approver rota before 31 December.

About this article. This is for maintainers, release engineers and platform teams who publish npm packages from CI. We checked every date, command, version and limit against npm's documentation, the GitHub Changelog, the npm registry, the GitHub Advisory Database, the StepSecurity and Socket incident reports, and US and UK government texts on 21 November 2026. npm changes these controls often, so re-check before you rely on them; this is not legal or compliance advice, and no vendor paid for inclusion. Researched with AI assistance and checked against the primary sources listed in the references.

What ends in January 2027, and what has already changed

npm's access-token page says bypass-2FA tokens with direct-publish access are being deprecated and that publishing new versions directly with a granular access token will be removed in January 2027. It tells you to move automation to a Read and write (stage only) token and the staging workflow. The page was last edited on 10 September 2026.

GitHub's changelog of 8 July 2026, which made npm v12 generally available, is narrower: 2FA-bypass tokens lose direct publishing around January 2027 and keep only reading private packages and staging a publish that a person approves with 2FA. The ways forward are trusted publishing with OIDC or staged publishing with human approval.

A token without bypass already meets a 2FA prompt on npm publish, which CI cannot answer, so plan on the docs' broader wording: from January, no granular token publishes directly from automation. We found no exact day in npm's docs or the GitHub Changelog as of 21 November.

The timeline draws on those pages, npm's trusted-publishing guide and three more changelog posts.

Date Change Source
November 2025 Legacy access tokens removed; only granular tokens remain npm docs
20 May 2026 Trusted-publisher configurations created before this date allow npm publish only npm docs
22 May 2026 Staged publishing generally available, npm CLI 11.15.0 or later GitHub Changelog
8 July 2026 npm v12 generally available; bypass-2FA deprecation announced GitHub Changelog
August 2026 Bypass-2FA tokens lose account, token, maintainer and organisation actions npm docs
3 September 2026 New trusted-publisher configurations allow npm stage publish by default npm docs
2 October 2026 Unvalidated trusted-publisher configurations expire after 48 hours; issue_comment tokens rejected; staging can create new packages GitHub Changelog
January 2027 Direct publishing with granular access tokens removed npm docs

The practical deadline is earlier. If your team freezes changes in late December, you want one real release through the new path before then. We suggest Friday 11 December 2026 as the date every pipeline is migrated and tested.

Why the bee-js release changes the advice

Swapping a token for trusted publishing is only half the job, as the 9 November compromise of @ethersphere/bee-js shows. GitHub's advisory lists version 13.3.0 as malware and says any machine that installed it should be treated as fully compromised.

StepSecurity reports that the malicious commit was made under the project's bee-worker release identity at 23:59:54 UTC on 8 November, and the v13.3.0 GitHub release followed under the same identity at 00:06:01 UTC on 9 November. That release started the existing workflow, which published 13.3.0 to npm at 00:09:50 UTC through GitHub Actions trusted publishing. Socket says npm removed it at 01:24:58 UTC, about 75 minutes later, and that bee-js had used trusted publishing, with no long-lived npm token, since January 2026.

Three details matter for this migration:

  • No npm token was needed. In Socket's reading, the project's own workflow, running its own code from the attacker's tag, published the attacker's commit.
  • The provenance was real. Socket verified the attestation end to end; it had the same shape as the clean 13.2.0 release, so provenance alone could not tell them apart.
  • Nothing paused the publish. The publish environment had no required reviewers, and the deployment went from creation to success in 73 seconds. A stage-only trusted publisher would have held 13.3.0 until a maintainer approved it with 2FA.

The reports differ on one point: StepSecurity describes an unsigned direct commit to the upcoming branch, while Socket says the commit belonged to no branch and never went through a pull request. How the credentials were stolen has not been established. Either way, the January cut-off closes the token path but does nothing about a trusted publisher still allowed to run npm publish straight to latest.

Which publish paths survive January 2027

Putting the token table in npm's stage reference next to the access-token page gives this picture.

Credential in CI npm publish today npm publish after January 2027 npm stage publish Provenance
Granular token, publish and stage, Bypass 2FA on Publishes if package publishing access allows Removed Can stage Only with the provenance flag on supported cloud CI
Granular token without bypass 2FA prompt, so CI fails Removed, per the docs wording Can stage As above
Granular token, stage only Rejected with E_STAGE_REQUIRED Same Can stage As above
Trusted publishing (OIDC) Publishes if direct publish is allowed Not named in the January removal Can stage if allowed Automatic on GitHub Actions and GitLab for a public repo and public package
Maintainer's interactive session 2FA prompt Unchanged Can stage None from a laptop

A stage-only token is not a general security boundary: it can still deprecate versions and move dist-tags, so guard it like any other secret. And the January removal, as npm words it, covers granular access tokens only, so a trust relationship that allows direct publish can still ship without a human.

Path A: OIDC trusted publishing on GitHub Actions, GitLab and CircleCI

npm supports trusted publishing from GitHub Actions on GitHub-hosted runners, GitLab CI/CD on GitLab.com shared runners, and CircleCI cloud. Self-hosted runners are not supported; npm says support is planned. Each package can have up to 10 trusted publishers.

Each trusted publisher binds identity fields: repository and workflow file for GitHub, project and CI file path for GitLab, organisation, project and pipeline IDs for CircleCI. Its allowed-actions setting decides whether the workflow may also run npm publish or npm dist-tag; npm stage publish is always allowed. Configurations created before 20 May 2026 were set to npm publish only, so check older ones. Dist-tag management over OIDC needs npm CLI 11.21.0 or 12.2.0 or later.

For many packages the CLI is faster. npm trust needs npm 11.15.0 or later and account 2FA, and refuses bypass-2FA tokens.


            # GitHub Actions: stage-only trust for one package
npm trust github @acme/ui-kit --file release.yml --repo acme/ui-kit \
  --env npm-release --allow-stage-publish --yes

# GitLab.com: stage-only trust
npm trust gitlab @acme/sdk --file .gitlab-ci.yml \
  --project acme/platform/sdk --allow-stage-publish --yes

# Check what is configured
npm trust list @acme/ui-kit
          

npm's bulk method is a loop with --yes: after the first 2FA challenge you can skip 2FA for five minutes, which with a two-second sleep between calls covers about 80 packages. One conflict: the npm trust page (edited 2 June 2026) allows one configuration per package, the trusted-publishing guide (edited 6 October 2026) allows 10. Add any second configuration on the website.

GitHub Actions workflow

Keep id-token: write on the publishing job only, and refuse release commits that are not on your protected branch, the check Socket says bee-js lacked.


            name: release
on:
  release:
    types: [published]
permissions:
  contents: read
jobs:
  stage:
    runs-on: ubuntu-latest
    environment: npm-release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Refuse release commits that are not on main
        run: git merge-base --is-ancestor "$GITHUB_SHA" origin/main
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'
          package-manager-cache: false
      - run: npm ci
      - run: npm test
      - run: npm stage publish
          

The branch check only helps if direct pushes to main are blocked. npm's example pins v6 of actions/checkout and actions/setup-node; both now have v7 releases, so pin the major you have tested, ideally by commit SHA.

The traps, per npm's docs: the workflow filename must match exactly, including .yml; repository.url in package.json must match the repository; and with workflow_call, validation checks the calling workflow's name and both workflows need id-token: write. npm does not check a configuration when you save it, so a mismatch surfaces as ENEEDAUTH at publish time. Since 2 October, npm also rejects trusted-publishing tokens from issue_comment events, alongside pull_request_target, so publish from push, release or workflow_dispatch. GitHub's separate default block on pull_request_target in public repositories starts on 2 December 2026, as our pull_request_target guide explains.

GitLab CI/CD job

GitLab needs an ID token with the npm audience, plus a Sigstore token for provenance.


            publish:
  stage: publish
  image: node:24
  id_tokens:
    NPM_ID_TOKEN:
      aud: "npm:registry.npmjs.org"
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - npm ci
    - npm run build --if-present
    - npm stage publish
  only:
    - tags
          

This works on GitLab.com shared runners only. Self-managed GitLab and GitLab.com projects on their own runners belong in Path B.

CircleCI job

CircleCI fetches an OIDC token in the job, and the npm CLI exchanges it for a short-lived publish token.


            export NPM_ID_TOKEN=$(circleci run oidc get --claims '{"aud": "npm:registry.npmjs.org"}')
npm stage publish
          

npm does not generate provenance for CircleCI trusted publishing, so these packages carry no attestation.

The 48-hour validation window

Since 2 October, a new trusted-publisher configuration must complete its first successful publish within 48 hours, which binds it to the repository's immutable identity. An expired one cannot be used or edited; delete it and create another. GitHub says this limits the risk of trusting a repository name that later changes hands. Neither page says whether a staged publish awaiting approval counts, so test the full cycle on one package first, and do not create trust relationships in bulk on a Friday unless you can push a pre-release before Sunday.

Path B: stage-only tokens for Jenkins, self-hosted runners and self-managed GitLab

Outside the three supported providers, staging with a granular token is the only automated route left: Jenkins, Azure Pipelines, Bitbucket Pipelines, TeamCity, Buildkite, self-hosted Actions runners and self-managed GitLab.

Create the token with Read and write (stage only) on specific packages or scopes, an expiry date and an IP range limited to your CI egress. Leave Bypass 2FA off, because staging never prompts for 2FA. One token covers up to 50 packages or scopes. Store it in the CI credential store and change one command.


            # .npmrc in the CI workspace
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

# Jenkins, Azure Pipelines, Bitbucket or self-hosted runner step
npm stage publish --tag latest
          

A leftover npm publish fails with E_STAGE_REQUIRED, the error to search for in January build logs. The staged tag cannot be changed, so a wrong tag means npm stage reject and a fresh stage, and pre-release versions need an explicit --tag. Since 2 October, npm stage publish can also create a new package; npm publishes a public 0.0.0-stage placeholder and keeps the real version private until a maintainer approves it.

Be careful with the package setting that disallows tokens: npm's docs say granular access tokens cannot be used under it, whatever their bypass flag, with no exception for staging, so leave token-staged packages on the default or test first. Self-hosted runners also give no provenance, because npm requires a cloud-hosted GitHub Actions or GitLab runner; if consumers want it, move only the release job to a hosted runner.

The approval step: who presses the button

Staging moves the risk decision from CI to a person, so approval needs an owner. OIDC tokens cannot approve: listing, viewing, approving and rejecting stages need interactive authentication on the CLI or npmjs.com.


            npm stage list @acme/ui-kit
npm stage view <stage-id>
npm stage download <stage-id>     # inspect the tarball
npm stage approve <stage-id> --otp 123456
          

On npmjs.com, the Staged Packages tab shows each version's dist-tag, publisher and SHASUM. Batch approval handles up to 100 versions with one 2FA challenge, one version per package, and npm says it is still rolling out.

Write down four rules before January:

  1. Who approves. At least two maintainers per package with 2FA, so a holiday does not block a hotfix.
  1. What they check. Version, dist-tag and publisher in npm stage view, a diff of package.json scripts against the last release, and whether the commit came from a merged pull request.
  1. How fast. For example, within four working hours, covering US Eastern and UK hours if maintainers span the Atlantic.
  1. Emergencies. A maintainer can still publish interactively with 2FA from a trusted device.

Once trusted publishing works for a package, npm recommends setting it to Require two-factor authentication and disallow tokens and revoking old automation tokens; that setting does not affect trusted publishers.

Provenance: what you keep, what you lose, what it proves

npm generates provenance automatically for trusted publishing from GitHub Actions or GitLab CI/CD when both the repository and the package are public, with no flag needed. Private repositories and CircleCI publishes get none. npm stage publish also accepts --provenance for token-based publishes from supported cloud CI.

npm's own docs say established provenance does not mean a package is free of malicious code; it gives a verifiable link to source and build instructions that you still have to judge. keyv shipped with valid GitHub Actions provenance in August, as our provenance and cooldown guide explains, and bee-js did the same in November. Provenance tells a consumer which repository, workflow and commit produced a tarball, which helps incident response. It is not a review. Consumers can verify attestations with npm audit signatures; publishers should pair provenance with protected release branches, a branch check and human approval for latest. Our npm supply-chain hardening article covers the consumer-side controls.

Decision table

Choose If
OIDC trusted publishing, stage only Your release job runs on GitHub-hosted runners, GitLab.com shared runners or CircleCI cloud, and you can staff approvals within a working day
OIDC trusted publishing, direct publish allowed You ship frequent canary or nightly builds to a non-latest tag, and you add required environment reviewers, protected tags and a branch check to reduce the bee-js risk
Stage-only granular token You run Jenkins, Azure Pipelines, Bitbucket, self-hosted runners or self-managed GitLab, or cannot move the release job to a hosted runner
Manual publish with 2FA A package ships a few times a year and automation would cost more than it saves
Move the release job to a hosted runner You need provenance for public packages but build on self-hosted infrastructure today

Avoid splitting one package across two release paths without a reason. Every extra trusted publisher or token is one more way to ship.

Worked example: a 120-person US and UK SaaS company

This example uses our planning assumptions, not measured data, and no vendor prices. The company has engineers in Boston and Manchester and publishes 30 npm packages: 20 public packages released from GitHub Actions, 6 private packages released from GitHub Actions in private repositories, and 4 packages built on a self-managed GitLab instance. It ships about 80 versions a month. Engineering time is costed at an assumed loaded rate of $110 an hour for the US team or £80 an hour for the UK team.


            One-off migration
  26 packages to OIDC trusted publishing       26 x 0.5 h = 13.0 h
  4 packages to stage-only tokens               4 x 1.0 h =  4.0 h
  12 release workflows edited and tested       12 x 1.5 h = 18.0 h
  Approval runbook, rota and dry runs                     =  6.0 h
  Total                                                   = 41.0 h

  US team: 41 x $110 = $4,510        UK team: 41 x £80 = £3,280

Ongoing approvals (batched twice a week)
  9 sessions a month x 15 minutes                         =  2.25 h
  4 major releases a month x 30 minutes of review         =  2.0 h
  Total                                                   =  4.25 h a month

  US team: 4.25 x $110 = $467.50     UK team: 4.25 x £80 = £340
          

The one-off cost is about a week of one engineer's time; the recurring half-day a month buys a human check on every version that reaches users. The 10 private-repository and GitLab packages (6 plus 4) get no provenance either way. Doing nothing is not free: from January, any package still on an NPM_TOKEN stops releasing until someone fixes it under pressure.

US and UK notes

United States. OMB memo M-26-05 of 23 January 2026 rescinded M-22-18 and M-23-16, the memos that made software producers selling to federal agencies attest to secure development practices. Agencies may still choose to use the Secure Software Development Attestation Form, which CISA released on 11 March 2024 and has since archived, and may ask for SBOMs by contract. The form is now an agency-by-agency request, not a blanket rule. Where a buyer still asks, short-lived OIDC credentials, a per-release approval record and provenance attestations are practical evidence, so keep the approval history and CI logs.

United Kingdom. The government's voluntary Software Security Code of Practice, co-designed with the NCSC and updated on 15 January 2026, sets 14 principles across four themes. In its build-environment theme, principle 2.1 covers keeping unauthorised access out of the build environment and 2.2 covers controlling and logging changes to it. Removing long-lived publish tokens and logging each approval map directly to those two. The code also says buyers can cite its principles in supplier contracts, and it comes with a self-assessment form vendors can share.

Migration checklist

  1. Inventory every publish path by Friday 27 November. Search CI configs for npm publish, NPM_TOKEN, NODE_AUTH_TOKEN and release tools that call npm, such as semantic-release or changesets. List each package, its CI system, its runner type and who maintains it.
  1. List tokens. In each maintainer's npm account, record which granular tokens have write access and Bypass 2FA enabled.
  1. Upgrade the CLI. Staging needs npm 11.15.0 or later and Node 22.14.0 or later; plain trusted publishing needs npm 11.5.1. The current CLI is 12.2.3, released on 18 November 2026, and npm 12 itself declares Node 22.22.2 or later on the 22 line, 24.15.0 or later on the 24 line, or Node 26.
  1. Create trust relationships in small batches you can validate within 48 hours, with stage-only permission.
  1. Swap the publish command. Replace npm publish with npm stage publish and push a pre-release through each path.
  1. Set up approvers, the rota and the review checklist above.
  1. Lock down by 11 December. On packages that publish through trusted publishing, select Require two-factor authentication and disallow tokens, then revoke old automation tokens. Leave token-staged packages on the default setting.
  1. Watch January builds for E_STAGE_REQUIRED and ENEEDAUTH, the two errors that point to a missed pipeline or a mismatched trust configuration.

Our TanStack trusted-publishing analysis goes deeper on isolating id-token: write, release caches and action pinning.

How eCorpIT can help

eCorpIT is a Gurugram-based technology organisation, founded in 2021, assessed at CMMI Level 5 and MSME certified, with senior-led engineering teams working across AWS, Microsoft and Google platforms. Our cybersecurity services team can inventory your npm publish paths, move release jobs to stage-only trusted publishing or stage-only tokens, and write the approval runbook your maintainers follow. Talk to us at /contact-us/.

Last updated: 21 November 2026.

References

  1. About access tokens (last edited 10 September 2026) — npm Docs
  1. npm install-time security and GAT bypass2fa deprecation, 8 July 2026 — GitHub Changelog
  1. Trusted publishing for npm packages (last edited 6 October 2026) — npm Docs
  1. Staged publishing for npm packages (last edited 10 November 2026) — npm Docs
  1. Unvalidated npm trusted publishing configurations now expire, 2 October 2026 — GitHub Changelog
  1. Malicious bee-js npm release and Swarm Desktop releases deliver SleepyDuck Ethereum C2 backdoor, 9 November 2026 — Socket
  1. npm-stage, CLI v12 command reference — npm Docs
  1. Staged publishing and new install-time controls for npm, 22 May 2026 — GitHub Changelog
  1. npm staged publishing now supports creating new packages, 2 October 2026 — GitHub Changelog
  1. Malware in @ethersphere/bee-js, GHSA-hh7j-5m3j-23pf, 9 November 2026 — GitHub Advisory Database
  1. @ethersphere/bee-js 13.3.0 compromised — StepSecurity
  1. npm-trust, CLI v12 command reference (last edited 2 June 2026) — npm Docs
  1. actions/checkout latest release (v7.0.1) — GitHub
  1. actions/setup-node latest release (v7.1.0) — GitHub
  1. pull_request_target blocked by default December 2, 2 November 2026 — GitHub Changelog
  1. Requiring 2FA for package publishing and settings modification — npm Docs
  1. Generating provenance statements — npm Docs
  1. M-26-05, Adopting a Risk-based Approach to Software and Hardware Security, 23 January 2026 — Office of Management and Budget
  1. Secure Software Development Attestation Form (archived content) — CISA
  1. Software Security Code of Practice (updated 15 January 2026) — GOV.UK, Department for Science, Innovation and Technology
  1. npm package document, versions and release times — npm registry

Frequently asked

Quick answers.

01 Can I still publish npm packages from CI with an access token after January 2027?
Not directly. npm's documentation says publishing new versions with a granular access token is removed in January 2027. A token can still stage a version with npm stage publish, and a maintainer then approves it with 2FA. For unattended releases, use OIDC trusted publishing from GitHub Actions, GitLab.com or CircleCI cloud.
02 What is the exact date in January 2027?
npm has not published one. Its access-token page says January 2027, and GitHub's 8 July 2026 changelog says around January 2027. As of 21 November 2026 no day had been announced, so plan for 1 January and finish the migration before any December change freeze your team runs.
03 Does trusted publishing still allow a direct npm publish?
Yes, if you allow it. Each trusted-publisher configuration has allowed actions: stage publish is always permitted, while direct publish and dist-tag management are optional. npm's docs do not include OIDC direct publish in the January removal. After the bee-js release, we recommend stage-only permission for anything that ships to the latest tag.
04 Which CI systems support npm trusted publishing?
GitHub Actions on GitHub-hosted runners, GitLab CI/CD on GitLab.com shared runners, and CircleCI cloud. Self-hosted runners are not supported yet, although npm says support is planned. Jenkins, Azure Pipelines, Bitbucket, self-managed GitLab and self-hosted Actions runners need a stage-only granular token and a maintainer approval for each version.
05 What does the E_STAGE_REQUIRED error mean?
It means a stage-only token tried to run npm publish. The registry rejects direct publishing for that token type and tells you to run npm stage publish instead, then have a maintainer approve the staged version. Seeing it in January build logs usually means a release script or tool still calls npm publish.
06 Should I set my packages to disallow tokens?
Only where releases go through trusted publishing. npm recommends that setting once OIDC works, and it does not affect trusted publishers. Its docs also say granular access tokens cannot be used under that setting, whatever their bypass flag, so packages that stage with a token from Jenkins or self-hosted runners should keep the default.
07 Do staged packages keep npm provenance?
They can. Trusted publishing from GitHub Actions or GitLab CI/CD generates provenance automatically when the repository and package are both public, and npm stage publish accepts the provenance flag. Private repositories, CircleCI and self-hosted runners produce none. Provenance shows where a package was built, not that anyone reviewed its source.
08 Why did trusted publishing not stop the bee-js compromise?
According to StepSecurity and Socket, the attacker used the project's release identity to publish a GitHub release, which triggered the legitimate publishing workflow. No npm token was needed and the provenance was genuine. The version went straight to the latest tag because nothing required approval. A stage-only trusted publisher would have held it for a maintainer.

About the author

Manu Shukla

Founder & Director

Founder of eCorpIT. Hands-on engineer leading senior-only delivery for AI apps, custom software, and cloud systems for global clients.

Subscribe

One engineering note a week. No fluff, no spam.

Senior-architect playbooks on AI agents, mobile apps, cloud, security, data, and marketing — delivered every Wednesday.

Past the reading

Read enough. Let's build something.

A senior architect responds in 24 working hours with scope, indicative cost, and a timeline. NDA before any technical conversation.

Loading search…

Browse all guides