Skip to content

docs(release): update npm publish flow for the post-Dec-2025 token model#38

Merged
dipto0321 merged 1 commit into
mainfrom
chore/release/fix-npm-token-docs
Jul 1, 2026
Merged

docs(release): update npm publish flow for the post-Dec-2025 token model#38
dipto0321 merged 1 commit into
mainfrom
chore/release/fix-npm-token-docs

Conversation

@dipto0321

Copy link
Copy Markdown
Owner

Summary

Fixes a real bug in the v1.0.0 release checklist: the "automation
token" guidance was based on npmjs.com's pre-Dec-2025 auth model.
Since the December 9, 2025 changes (classic tokens permanently
revoked, session-based login, granular tokens the only option for
browser-generated publish tokens), that token type does not
exist anymore
. The current docs would have sent the user to a
token-type dropdown that isn't there.

Replaces the stale section with two current options:

  • OIDC Trusted Publishing (recommended) — GitHub Actions
    exchanges its built-in OIDC token for a one-hour publish token
    scoped to the nodeup-cli package. No GitHub secret to create
    or rotate, no token to leak, per-package config in the npm
    package's "Trusted Publisher" UI.
  • Granular access token as NPM_TOKEN — browser-only flow
    (npm doesn't yet support granular-token creation via the CLI),
    90-day max expiry, package-scoped, optional bypass_2fa for
    unattended CI. Use this if you publish from non-GitHub CI or
    want a human-readable audit trail of which token published
    which version.

Also tightens the 2FA section (TOTP authenticator-app required;
SMS/email modes don't work for publish) and the manual npm login
section (now a short-lived session token, ~2-hour expiry, separate
OTP prompts for login vs publish).

Linked issues

Refs #35 (tracking issue for the npm-publish step)

Type of change

  • feat — new feature (MINOR bump)
  • fix — bug fix (PATCH bump)
  • refactor — no behavior change
  • docs — documentation only
  • chore — maintenance / dependency bump
  • ci — CI/CD only
  • build — build system only
  • Breaking change (MAJOR bump) — explain below

Checklist

  • Title follows Conventional Commits (docs(release): subject)
  • I ran make ci locally — docs-only, no code change
  • I added or updated tests — N/A, docs only
  • I updated relevant docs (this PR IS the doc update)
  • No new linter warnings

Scope notes / things reviewers may want to look at

  • Real bug. A user following the v1.0.0 checklist would have
    gone to the npm token page looking for an "Automation" type
    that no longer exists. This is a doc fix that prevents a
    release-day blocker.
  • Why the prior version slipped through. The earlier
    "Add NPM_TOKEN" guidance in the checklist (and the gh secret set NPM_TOKEN step in the plan) was correct as of the project
    planning phase but became stale when npm shipped the
    December 2025 auth changes. The right fix is to update the
    checklist now rather than wait until release time.
  • Two options, one recommended. OIDC is the cleanest fit for
    GitHub Actions and is what I'd wire up for the v1.0.0 release
    workflow. Granular tokens are kept in the docs as a fallback
    for non-GH CI and for users who prefer a tangible secret to
    audit. Both end with npm publish --provenance --access public,
    which is now required for packages linked to public repos.

How to verify

Read the post-tag section of docs/release-checklist.md:
"Publishing nodeup-npm to the npm registry" → "Can I automate
it?" — the two options there should be OIDC first, granular
token second. The manual section above it should now mention
session-token expiry and the dual-OTP behavior.

The "Publish-only automation token" guidance in the v1.0.0 release
checklist was based on npmjs.com's pre-Dec-2025 auth model. Since
the December 9, 2025 changes (classic tokens permanently revoked,
session-based login with ~2-hour expiry, granular tokens the only
option for browser-generated publish tokens), that type no longer
exists.

Replaces the stale "Add a NPM_TOKEN automation token" section with
two current options:

- OIDC Trusted Publishing (recommended): GitHub Actions exchanges
  its OIDC token for a one-hour publish token scoped to the
  nodeup-cli package. No GitHub secret, no rotation, no leak surface.
  Per-package config in the npm package's "Trusted Publisher" UI.

- Granular access token as NPM_TOKEN: browser-only flow (npm
  doesn't yet support granular-token creation via the CLI), 90-day
  max expiry, package-scoped, optional bypass_2fa. Use this if
  publishing from non-GitHub CI or if you want a human-readable
  audit trail of which token published which version.

Also tightens the 2FA and npm login sections to mention the new
session-token-with-2h-expiry behavior and to require an
authenticator-app (TOTP) factor explicitly.

Refs #35.

Co-Authored-By: Sonnet 4.6 <noreply@puku.sh>
@cocogitto-bot

cocogitto-bot Bot commented Jul 1, 2026

Copy link
Copy Markdown

✔️ 976327f - Conventional commits check succeeded.

@dipto0321 dipto0321 merged commit 6078b44 into main Jul 1, 2026
10 checks passed
@dipto0321 dipto0321 deleted the chore/release/fix-npm-token-docs branch July 1, 2026 20:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant