diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index d3098a4..6909329 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -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 @@ -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 diff --git a/RELEASING.md b/RELEASING.md index e57bde0..b1ce3e1 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -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` 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.