Skip to content

Use staged npm publishing for releases #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
konojunya merged 1 commit into from
Sep 3, 2026
Merged

Use staged npm publishing for releases #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/release.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ jobs:
registry-url: https://registry.npmjs.org
package-manager-cache: false

- name: Install trusted publishing npm CLI
run: npm install --global npm@11.5.1
- name: Install staged publishing npm CLI
run: npm install --global npm@11.15.0

- name: Install JavaScript development dependencies
run: npm ci
Expand Down Expand Up @@ -84,6 +84,6 @@ jobs:
echo "published=false" >> "$GITHUB_OUTPUT"
fi

- name: Publish package
- name: Stage package for publishing
if: steps.package.outputs.published != 'true'
run: npm publish --workspace @stack-sh/engine --access public
run: npm stage publish --workspace @stack-sh/engine --access public
12 changes: 7 additions & 5 deletions RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,17 +22,19 @@ After `@stack-sh/engine` exists on npm, configure its trusted publisher with the
- Organization: `stack-sh`
- Repository: `engine`
- Workflow filename: `release.yaml`
- Allowed action: `npm publish`
- Allowed action: `npm stage publish`

Then create the `v0.1.0` GitHub Release from the same merged revision. The release workflow recognizes that the package version already exists and completes without publishing it twice.
Then create the `v0.1.0` GitHub Release from the same merged revision. The release workflow recognizes that the package version already exists and completes without staging it twice.

If a published release needs to resume after a workflow-only correction, run the Release workflow manually with the existing exact tag. The recovery path checks out that tag and applies the same version, ancestry, build, test, package-content, and publication checks before it can publish.
If a published release needs to resume after a workflow-only correction, run the Release workflow manually with the existing exact tag. The recovery path checks out that tag and applies the same version, ancestry, build, test, and package-content checks before it can stage the package. Do not rerun the workflow after a version has entered the staging area; inspect or reject that staged version instead.

## Subsequent releases

1. Update the workspace and package versions in a pull request.
2. Run the complete repository checks and merge the pull request.
3. Create a GitHub Release whose tag is exactly `v<package version>` and targets the merged commit.
4. Verify that the release workflow publishes the package through npm trusted publishing.
4. Verify that the release workflow stages the package through npm trusted publishing.
5. Inspect the staged package on npm, then approve it with two-factor authentication.
6. Verify the public registry metadata, provenance, and a clean consumer installation.

The workflow rejects a tag that does not match the package version. It builds and validates the package again on the tagged revision, uses no long-lived npm token, and leaves npm provenance enabled.
The workflow rejects a tag that does not match the package version. It builds and validates the package again on the tagged revision, uses no long-lived npm token, and leaves npm provenance enabled. A package does not become public until a maintainer explicitly approves the staged version with two-factor authentication.