From 913df7c5ed20894b6c3daa39ddca918bfd55197e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lucas=20N=C3=B8rg=C3=A5rd?= <lucasnrgaard@gmail.com>
Date: Tue, 2 Jun 2026 20:23:35 +0200
Subject: [PATCH 1/2] feat(npm): add support for staged publishing with pnpm

Introduce a new input `stage` to enable `pnpm stage publish` for npm's staged publishing workflow. This allows for verification of release artifacts before final approval to the live registry.
---
 .github/workflows/reusable-release-npm.md   | 19 +++++++++++++++++++
 .github/workflows/reusable-release-npm.yaml | 15 +++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/.github/workflows/reusable-release-npm.md b/.github/workflows/reusable-release-npm.md
index 56f5a5a..4143475 100644
--- a/.github/workflows/reusable-release-npm.md
+++ b/.github/workflows/reusable-release-npm.md
@@ -54,6 +54,7 @@ jobs:
 | `publish-args` | `string` | `--access public --no-git-checks` | Additional arguments passed to `pnpm publish`. |
 | `generate-changelog` | `boolean` | `true` | Generate a GitHub release changelog with `changelogithub`. |
 | `install-args` | `string` | `""` | Additional arguments passed to `pnpm install`. |
+| `stage` | `boolean` | `false` | Use `pnpm stage publish` for npm's staged publishing workflow instead of direct publishing. |
 
 ## Secrets
 
@@ -81,6 +82,24 @@ The workflow uses `git describe --tags --abbrev=0` to find the latest tag:
 - Tags containing `-` publish with the `next` dist-tag.
 - Other tags publish with the `latest` dist-tag.
 
+## Staged Publishing
+
+When `stage: true` is passed, the workflow uses `pnpm stage publish` instead of `pnpm publish`. This enables npm's staged publishing workflow, which uploads to staging and defers proof-of-presence (2FA) to a later point. This is useful for verifying release artifacts or smoke-testing before approving the final release to the live registry.
+
+To use staged publishing:
+
+```yaml
+jobs:
+  release:
+    permissions:
+      id-token: write
+      contents: write
+    uses: luxass/shared-workflows/.github/workflows/reusable-release-npm.yaml@v0.8.2
+    with:
+      stage: true
+    secrets: inherit
+```
+
 ## Jobs
 
 | Job | Description |
diff --git a/.github/workflows/reusable-release-npm.yaml b/.github/workflows/reusable-release-npm.yaml
index 29da52f..da776d8 100644
--- a/.github/workflows/reusable-release-npm.yaml
+++ b/.github/workflows/reusable-release-npm.yaml
@@ -43,6 +43,11 @@ on:
         type: string
         default: ""
         required: false
+      stage:
+        description: "Use pnpm stage publish instead of pnpm publish"
+        type: boolean
+        default: false
+        required: false
 
 permissions: {}
 
@@ -100,7 +105,17 @@ jobs:
             echo "tag=latest" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: publish to npm (staging)
+        if: ${{ inputs.stage }}
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+          NPM_CONFIG_PROVENANCE: "true"
+          PUBLISH_ARGS: ${{ inputs.publish-args }}
+          RECURSIVE: ${{ inputs.recursive }}
+        run: pnpm stage publish ${{ env.RECURSIVE == 'true' && '-r' || '' }} --tag "$TAG" $PUBLISH_ARGS
+
       - name: publish to npm
+        if: ${{ !inputs.stage }}
         env:
           TAG: ${{ steps.tag.outputs.tag }}
           NPM_CONFIG_PROVENANCE: "true"

From ec3bb3fa2fc2c899b69161786f347d3a7e3b693b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lucas=20N=C3=B8rg=C3=A5rd?= <lucasnrgaard@gmail.com>
Date: Tue, 2 Jun 2026 20:47:04 +0200
Subject: [PATCH 2/2] docs: update reusable-release-npm.md with staged
 publishing requirements

Added version requirements for `pnpm` and `Node.js` to support npm's staged publishing workflow. This includes specifying the minimum versions needed for `pnpm stage publish` and `npm CLI`.
---
 .github/workflows/reusable-release-npm.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/workflows/reusable-release-npm.md b/.github/workflows/reusable-release-npm.md
index 4143475..757ea4e 100644
--- a/.github/workflows/reusable-release-npm.md
+++ b/.github/workflows/reusable-release-npm.md
@@ -86,6 +86,11 @@ The workflow uses `git describe --tags --abbrev=0` to find the latest tag:
 
 When `stage: true` is passed, the workflow uses `pnpm stage publish` instead of `pnpm publish`. This enables npm's staged publishing workflow, which uploads to staging and defers proof-of-presence (2FA) to a later point. This is useful for verifying release artifacts or smoke-testing before approving the final release to the live registry.
 
+Version requirements for staged publishing:
+
+- `pnpm >= 11.3.0` (required for `pnpm stage publish`)
+- `Node.js >= 22.14.0` and `npm CLI >= 11.15.0` (required for npm staged publishing)
+
 To use staged publishing:
 
 ```yaml