feat(tokens): document stage-only access tokens - #2036
Merged
Merged
Conversation
Document the new "Read and write (stage only)" granular access token publish policy (github/npm#15610, epic github/npm#15530). - about-access-tokens: add "About stage-only tokens" section covering capabilities (stage, deprecate, dist-tags, unpublish), the limitation (no direct publish; E_STAGE_REQUIRED), the npm stage publish -> maintainer npm stage approve promotion flow, and the Jan 2027 direct-publish deprecation. Avoids overstating security. - creating-and-viewing-access-tokens: update the now-live Packages and scopes permission options ("Read and write (publish and stage)" / "Read and write (stage only)"). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0f2e357f-6da8-4978-a637-f14539820093
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
A few documentation statements need tightening/consistency fixes, and the Jan 2027 scope is flagged as undecided but currently stated definitively in the doc.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review tier: Lite
Findings: 3
New issues introduced by this change (3)
| Severity | Finding |
|---|---|
 |
content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx — In this bullet, the permission labels are lowercased ("read-only" / "read and write"), but… |
|
content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx — This sentence implies stage-only tokens are "safer" because they can't push a version live, but the… |
|
content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx — The PR description flags an open decision about whether the Jan 2027 cutoff applies to all… |
What changed in this PR
Adds public documentation for the new “Read and write (stage only)” granular access token publish policy, and updates the token-creation documentation to match the production UI permission labels.
Changes:
- Documented stage-only tokens (capabilities, limitations, staging/promotion workflow, and deprecation timeline messaging) in
about-access-tokens.mdx. - Updated Packages and scopes → Permissions options and added brief explanations/links in
creating-and-viewing-access-tokens.mdx.
| File | Description |
|---|---|
| content/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens.mdx | Updates UI permission option labels and adds short explanations + link to stage-only token docs. |
| content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx | Adds “About stage-only tokens” section and references it from the granular token capability list, including deprecation messaging. |
Suppressed comments (1)
content/integrations/integrating-npm-with-external-services/about-access-tokens.mdx:69
- Grammar: "Stage-only restricts" reads like an adjective without a subject. Changing to "A stage-only token restricts" makes the note clearer.
**Note:** Stage-only restricts _direct publishing of new versions only_. It is not a general-purpose security boundary — a stage-only token retains the other write capabilities listed above, so treat it with the same care as any other token.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
dhei
reviewed
Sep 10, 2026
dhei
reviewed
Sep 10, 2026
dhei
approved these changes
Sep 10, 2026
- Scope the January 2027 deprecation to bypass-2FA direct-publish tokens (dhei review; matches github/npm#15610). - State the narrow security guarantee (no direct new-version publish without maintainer approval) instead of implying broad safety (Copilot review). - Title-case the Read-only / Read and write permission labels to match the UI and the token-creation doc, and add a trailing period (Copilot review). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0f2e357f-6da8-4978-a637-f14539820093
Unpublish is not governed by the stage-only publish policy but by the bypass-2FA GAT allowlist (npm-auth-ws, github/npm#15226): a 2FA-bypass granular access token — the population stage-only automation tokens fall into — is blocked from unpublish (403), while deprecate and dist-tags remain allowed. Verified against enforcement code and a live test (dhei review). Keep deprecate and dist-tags; remove the overstated unpublish claim. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0f2e357f-6da8-4978-a637-f14539820093
dhei
added a commit
to npm/api-documentation
that referenced
this pull request
Sep 11, 2026
Related to docs.npmjs.com PR npm/documentation#2036
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds public documentation for the new "Read and write (stage only)" granular access token publish policy.
Part of github/npm#15530 (Phase 1 — safer stage-capable GAT). Closes github/npm#15610.
Changes
about-access-tokens.mdx— new### About stage-only tokenssection covering:npm stage publish), deprecate, move dist-tags, unpublish; cannot directly publish a new version (fails withE_STAGE_REQUIRED).npm stage publish→ maintainer with 2FA runsnpm stage approve <stage-id> --otp <code>.<Note>explicitly stating this is not a general-purpose security boundary (avoids overstating security, per the issue).creating-and-viewing-access-tokens.mdx— updates the now-live Packages and scopes permission options to match the production UI (wubwub #3762, deployed at 100%): Read and write (publish and stage) / Read and write (stage only).