Support npm staged publishing in changeset publish · Issue #2025 · changesets/changesets · GitHub
Skip to content

Support npm staged publishing in changeset publish #2025

Open
Feature
Open
Support npm staged publishing in changeset publish#2025
Feature

Description

@diegohaz
diegohaz
opened on May 21, 2026

Affected Packages

@changesets/cli
@changesets/action

Problem

npm recently added staged publishing via npm stage publish in npm CLI 11.15.0. This lets CI submit a package version to npm without making it public immediately. A maintainer can then review the staged package and explicitly approve it with 2FA before it goes live.

Today, changeset publish only supports immediate publishing through normal package-manager publishing. In a Changesets monorepo, teams who want npm staged publishing need custom scripting for package selection, publish dirs, access/tag handling, ignored/private packages, and post-approval tagging.

npm docs: https://docs.npmjs.com/staged-publishing/

Proposed Solution

Add first-class support for npm staged publishing.

Possible API:

changeset publish --stage

or:

changeset publish --publish-mode=stage

When enabled, Changesets would use npm stage publish instead of immediate publishing for packages that need publishing.

The staged mode should probably avoid creating git tags during the staging step, because a staged package is not live yet and may be rejected. A safe flow would be:

  1. changeset version
  2. build packages
  3. changeset publish --stage
  4. maintainer reviews staged packages with npm stage list, npm stage view, and/or npm stage download
  5. maintainer approves staged packages with npm stage approve <stage-id>
  6. run changeset tag or another finalize step after approval

Notes / Constraints

npm staged publishing has a few constraints that Changesets could account for or document:

  • Requires npm CLI 11.15.0 or later.
  • Requires Node 22.14.0 or later.
  • npm stage is not workspace-aware.
  • The package must already exist on the npm registry; brand-new packages cannot be staged.
  • npm stage publish does not require 2FA, but npm stage approve does.
  • The tag used during staging is immutable; changing it requires rejecting and staging again.

Activity

  1. Andarist commented on May 21, 2026

    @Andarist
    Andarist
    on May 21, 2026
    Member

    Hey, this is very much on my mind and I'm figuring out how ot best support this and related workflows.

    In the meantime, I recommend using a split workflow like the one we currently have here: https://github.com/changesets/changesets/blob/372523f4c2ee4ffeb8330d444d47ffb6d0af5126/.github/workflows/publish.yml

    This one should be configured together with a manual environment approval.

  2. bluwy
    added the
    Feature
    issue type on May 26, 2026
  3. jerelmiller
    added a commit that references this issue on May 27, 2026

    run `npm stage publish` instead of `npm publish` in changesets (#13245)

    189d166
  4. beeequeue
    added this to the v3 milestone on May 28, 2026
  5. stijnvanhulle
    added 2 commits that reference this issue on Jul 3, 2026

    ci(release): tag after verified approval, not at stage time

    b191a1f

    ci(release): gate public release signals behind npm approval

    bbf5e74
  6. bluwy
    removed this from the v3 milestone on Aug 3, 2026
  7. noshiro-pf
    added 4 commits that reference this issue on Sep 11, 2026

    fix(ci): declare least-privilege permissions and pin the release envi…

    0b0ea73

    fix(ci): declare least-privilege permissions and pin the release envi…

    3458f2d

    fix(ci): declare least-privilege permissions and pin the release envi…

    19239cc

    feat(github-settings-as-code): manage the default workflow permissions (

    91288ce
  8. lollipop-onl
    added a commit that references this issue on Sep 27, 2026

    ci: stage releases on npm for a maintainer to approve with 2FA (#22)

    d293108

  9. jeremy-code commented on Oct 4, 2026

    @jeremy-code
    jeremy-code
    on Oct 4, 2026

    If you want to use staged publishing and are using GitHub Actions, you can do this with a custom publish script. You can't run it inline though, because the changesets action runs the command in execa and not in a shell.

    #!/bin/bash

# npm
npm stage publish --json \
  | jq --compact-output '.[] | {type: "git-tag", tag: .id, packageName: .name}' > $CHANGESETS_OUTPUT

# pnpm
# Unfortunately, pnpm outputs messages on stdout and not stderr like npm, so if
# you want meaningful error messages, you will have to run publish twice
pnpm stage publish --recursive --reporter silent --json --dry-run \
  | jq --compact-output '.[] | {type: "git-tag", tag: .id, packageName: .name}' > $CHANGESETS_OUTPUT
pnpm stage publish

    If you're using pnpm specifically, you can also do this using pnpm-publish-summary.json:

    #!/bin/bash

pnpm stage publish --recursive --report-summary

cat pnpm-publish-summary.json \
  | jq --compact-output '.publishedPackages[] | {type: "git-tag", tag: .id, packageName: .name}' > $CHANGESETS_OUTPUT

  10. rexxars commented on Oct 12, 2026

    @rexxars
    rexxars
    on Oct 12, 2026

    Are there any proposals/thoughts on how you'd want to model and support staged publishing in changesets natively? Would be happy to contribute to this if there is.

  11. evenstensberg commented on Oct 14, 2026

    @evenstensberg
    evenstensberg
    on Oct 14, 2026

    Interested in trying out and giving feedback from a webpack pov when there's a way for staged publishing to work with changesets.

    For now, we've added OICD on npm and allowing npm publish so that the changeset doesn't fail on publish

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Feature

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions