From 426a09c170d80dad6dc3eba13cd4c461687385ae Mon Sep 17 00:00:00 2001 From: MK Date: Sat, 14 Nov 2026 22:32:29 +0800 Subject: [PATCH 1/5] ci: publish npm releases from version change PRs --- .github/RELEASING.md | 40 ++++++++++ .github/workflows/release.yml | 135 ++++++++++++++++++++++++++++++++-- README.md | 5 ++ 3 files changed, 175 insertions(+), 5 deletions(-) create mode 100644 .github/RELEASING.md diff --git a/.github/RELEASING.md b/.github/RELEASING.md new file mode 100644 index 0000000..e508910 --- /dev/null +++ b/.github/RELEASING.md @@ -0,0 +1,40 @@ +# Releasing + +Maintainers choose the release version in a pull request. Commit messages do not +trigger automatic version bumps or npm releases. + +1. Create a branch from `master`. +2. Update `package.json` with `npm version patch --no-git-tag-version`, or choose + the required minor, major, or explicit version. +3. Add the release notes to `CHANGELOG.md` and open a PR into `master`. +4. Merge the PR after its CI checks pass. + +The `Release` workflow compares the package versions before and after the push +to `master`. It requires an associated merged PR. Dependency-only changes and +direct version pushes do not publish a package. + +The workflow checks out the exact merged commit, installs dependencies, and runs +`npm run ci`, including the build and package type checks. It publishes stable +versions with the `latest` npm tag and prerelease versions with `next`. It then +creates a `v` tag and a GitHub release with generated notes. + +If a release fails, rerun its failed jobs in GitHub Actions. The workflow skips +versions that already exist on npm and GitHub releases that already exist, so a +retry can finish creating the GitHub release without publishing the package again. + +## npm trusted publisher + +Configure the `utility` package's trusted publisher on npm with: + +- Organization: `node-modules` +- Repository: `utility` +- Workflow filename: `release.yml` +- Environment: leave empty +- Allowed action: `npm publish` + +The workflow uses Node.js 24, npm 11, and `id-token: write` for OIDC authentication. +It does not use an npm token or the `GIT_TOKEN` secret. GitHub release creation +uses the repository's built-in `GITHUB_TOKEN`. + +See the [npm trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/) +for the package settings. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b8d6a72..62d118a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -3,10 +3,135 @@ name: Release on: push: branches: [ master ] + paths: [ package.json ] + +permissions: + contents: read jobs: - release: - name: NPM - uses: node-modules/github-actions/.github/workflows/npm-release.yml@master - secrets: - GIT_TOKEN: ${{ secrets.GIT_TOKEN }} + version: + name: Check version PR + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + outputs: + changed: ${{ steps.version.outputs.changed }} + version: ${{ steps.version.outputs.version }} + npm_tag: ${{ steps.version.outputs.npm_tag }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Check for a merged version change + id: version + uses: actions/github-script@v7 + with: + script: | + const { execFileSync } = require('node:child_process'); + const readPackage = ref => JSON.parse(execFileSync( + 'git', ['show', `${ref}:package.json`], { encoding: 'utf8' } + )); + const previous = readPackage(context.payload.before); + const current = readPackage(context.sha); + if (previous.version === current.version) { + core.info('The package version did not change.'); + return; + } + if (current.name !== previous.name || typeof current.version !== 'string') { + throw new Error('The release must keep the package name and specify a version.'); + } + const prs = await github.paginate(github.rest.repos.listPullRequestsAssociatedWithCommit, { + ...context.repo, + commit_sha: context.sha, + }); + if (!prs.some(pr => pr.merged_at && pr.base.ref === 'master' + && pr.base.repo.full_name === `${context.repo.owner}/${context.repo.repo}`)) { + core.info('The version change must come from a merged PR into master.'); + return; + } + core.setOutput('changed', 'true'); + core.setOutput('version', current.version); + core.setOutput('npm_tag', current.version.includes('-') ? 'next' : 'latest'); + + publish: + name: Publish to npm + needs: version + if: needs.version.outputs.changed == 'true' + runs-on: ubuntu-latest + permissions: + contents: write + id-token: write + concurrency: + group: npm-release + cancel-in-progress: false + env: + RELEASE_VERSION: ${{ needs.version.outputs.version }} + NPM_TAG: ${{ needs.version.outputs.npm_tag }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.sha }} + persist-credentials: false + + - uses: actions/setup-node@v4 + with: + node-version: '24' + registry-url: https://registry.npmjs.org + + - name: Use npm with trusted publishing support + run: npm install --global npm@11 + + - name: Check whether the version is already published + id: npm + uses: actions/github-script@v7 + with: + script: | + const { readFileSync } = require('node:fs'); + const { name, version } = JSON.parse(readFileSync('package.json', 'utf8')); + const response = await fetch( + `https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(version)}` + ); + if (response.status === 404) { + core.setOutput('published', 'false'); + } else if (response.ok) { + core.info(`${name}@${version} is already published.`); + core.setOutput('published', 'true'); + } else { + throw new Error(`npm registry check failed: ${response.status}`); + } + + - name: Install dependencies + if: steps.npm.outputs.published == 'false' + run: npm install --no-package-lock --no-fund + + - name: Check, build, and test + if: steps.npm.outputs.published == 'false' + run: npm run ci + + - name: Publish with npm trusted publishing + if: steps.npm.outputs.published == 'false' + run: npm publish --provenance --access public --tag "$NPM_TAG" + + - name: Create GitHub release + uses: actions/github-script@v7 + with: + script: | + const tag = `v${process.env.RELEASE_VERSION}`; + try { + await github.rest.repos.getReleaseByTag({ ...context.repo, tag }); + core.info(`${tag} already has a GitHub release.`); + return; + } catch (error) { + if (error.status !== 404) throw error; + } + await github.rest.repos.createRelease({ + ...context.repo, + tag_name: tag, + target_commitish: context.sha, + name: tag, + generate_release_notes: true, + prerelease: process.env.NPM_TAG === 'next', + }); diff --git a/README.md b/README.md index 4d3c8ef..ce101c7 100644 --- a/README.md +++ b/README.md @@ -359,6 +359,11 @@ new Date().toString() x 816,731 ops/sec ±3.46% (93 runs sampled) Fastest is utils.datestruct().YYYYMMDD ``` +## Releasing + +See the [release guide](.github/RELEASING.md) for the version PR and npm trusted +publishing process. + ## License [MIT](LICENSE.txt) From bda8899925b7b1b519b35f5f15a9f395f9cc97e0 Mon Sep 17 00:00:00 2001 From: MK Date: Sat, 14 Nov 2026 22:34:51 +0800 Subject: [PATCH 2/5] ci: avoid repeating PR checks during release --- .github/RELEASING.md | 9 +++++---- .github/workflows/release.yml | 4 ---- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/.github/RELEASING.md b/.github/RELEASING.md index e508910..35d272d 100644 --- a/.github/RELEASING.md +++ b/.github/RELEASING.md @@ -13,10 +13,11 @@ The `Release` workflow compares the package versions before and after the push to `master`. It requires an associated merged PR. Dependency-only changes and direct version pushes do not publish a package. -The workflow checks out the exact merged commit, installs dependencies, and runs -`npm run ci`, including the build and package type checks. It publishes stable -versions with the `latest` npm tag and prerelease versions with `next`. It then -creates a `v` tag and a GitHub release with generated notes. +The workflow checks out the exact merged commit and installs dependencies. +`npm publish` runs the `prepublishOnly` script to build the package. The release +workflow relies on the PR's CI checks and does not run them again. It publishes +stable versions with the `latest` npm tag and prerelease versions with `next`. +It then creates a `v` tag and a GitHub release with generated notes. If a release fails, rerun its failed jobs in GitHub Actions. The workflow skips versions that already exist on npm and GitHub releases that already exist, so a diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 62d118a..3d85829 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -107,10 +107,6 @@ jobs: if: steps.npm.outputs.published == 'false' run: npm install --no-package-lock --no-fund - - name: Check, build, and test - if: steps.npm.outputs.published == 'false' - run: npm run ci - - name: Publish with npm trusted publishing if: steps.npm.outputs.published == 'false' run: npm publish --provenance --access public --tag "$NPM_TAG" From 6dfb0cd6e8c483700854a350c5d10ef77ff4d41c Mon Sep 17 00:00:00 2001 From: MK Date: Sat, 14 Nov 2026 22:37:17 +0800 Subject: [PATCH 3/5] ci: trigger releases directly from version changes --- .github/RELEASING.md | 7 ++++--- .github/workflows/release.yml | 16 ++-------------- 2 files changed, 6 insertions(+), 17 deletions(-) diff --git a/.github/RELEASING.md b/.github/RELEASING.md index 35d272d..6729087 100644 --- a/.github/RELEASING.md +++ b/.github/RELEASING.md @@ -10,10 +10,11 @@ trigger automatic version bumps or npm releases. 4. Merge the PR after its CI checks pass. The `Release` workflow compares the package versions before and after the push -to `master`. It requires an associated merged PR. Dependency-only changes and -direct version pushes do not publish a package. +to `master` and publishes when the version changes. Dependency-only changes do +not publish a package. The workflow does not check whether the push came from a +PR; branch protection can enforce that repository policy. -The workflow checks out the exact merged commit and installs dependencies. +The workflow checks out the exact pushed commit and installs dependencies. `npm publish` runs the `prepublishOnly` script to build the package. The release workflow relies on the PR's CI checks and does not run them again. It publishes stable versions with the `latest` npm tag and prerelease versions with `next`. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3d85829..160706e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -10,11 +10,8 @@ permissions: jobs: version: - name: Check version PR + name: Check version change runs-on: ubuntu-latest - permissions: - contents: read - pull-requests: read outputs: changed: ${{ steps.version.outputs.changed }} version: ${{ steps.version.outputs.version }} @@ -25,7 +22,7 @@ jobs: fetch-depth: 0 persist-credentials: false - - name: Check for a merged version change + - name: Compare package versions id: version uses: actions/github-script@v7 with: @@ -43,15 +40,6 @@ jobs: if (current.name !== previous.name || typeof current.version !== 'string') { throw new Error('The release must keep the package name and specify a version.'); } - const prs = await github.paginate(github.rest.repos.listPullRequestsAssociatedWithCommit, { - ...context.repo, - commit_sha: context.sha, - }); - if (!prs.some(pr => pr.merged_at && pr.base.ref === 'master' - && pr.base.repo.full_name === `${context.repo.owner}/${context.repo.repo}`)) { - core.info('The version change must come from a merged PR into master.'); - return; - } core.setOutput('changed', 'true'); core.setOutput('version', current.version); core.setOutput('npm_tag', current.version.includes('-') ? 'next' : 'latest'); From 9603d84153c4734ee16f9d45c03074b3190fe6d1 Mon Sep 17 00:00:00 2001 From: MK Date: Sat, 14 Nov 2026 22:41:35 +0800 Subject: [PATCH 4/5] ci: preserve queued releases and protect latest tag --- .github/RELEASING.md | 6 ++++++ .github/workflows/release.yml | 22 +++++++++++++++------- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/.github/RELEASING.md b/.github/RELEASING.md index 6729087..b948bf0 100644 --- a/.github/RELEASING.md +++ b/.github/RELEASING.md @@ -19,6 +19,12 @@ The workflow checks out the exact pushed commit and installs dependencies. workflow relies on the PR's CI checks and does not run them again. It publishes stable versions with the `latest` npm tag and prerelease versions with `next`. It then creates a `v` tag and a GitHub release with generated notes. +Release jobs run one at a time, with up to 100 pending jobs queued. + +Stable releases use npm's default `latest` tag without an explicit `--tag` option. +If a newer stable version is already published, npm rejects an older unpublished +version instead of moving `latest` backward. This also applies when retrying an +older release job. If a release fails, rerun its failed jobs in GitHub Actions. The workflow skips versions that already exist on npm and GitHub releases that already exist, so a diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 160706e..756b18f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -17,14 +17,14 @@ jobs: version: ${{ steps.version.outputs.version }} npm_tag: ${{ steps.version.outputs.npm_tag }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7.0.1 with: fetch-depth: 0 persist-credentials: false - name: Compare package versions id: version - uses: actions/github-script@v7 + uses: actions/github-script@v9.0.0 with: script: | const { execFileSync } = require('node:child_process'); @@ -55,26 +55,28 @@ jobs: concurrency: group: npm-release cancel-in-progress: false + queue: max env: RELEASE_VERSION: ${{ needs.version.outputs.version }} NPM_TAG: ${{ needs.version.outputs.npm_tag }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v7.0.1 with: ref: ${{ github.sha }} persist-credentials: false - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v7.1.0 with: node-version: '24' registry-url: https://registry.npmjs.org + package-manager-cache: false - name: Use npm with trusted publishing support run: npm install --global npm@11 - name: Check whether the version is already published id: npm - uses: actions/github-script@v7 + uses: actions/github-script@v9.0.0 with: script: | const { readFileSync } = require('node:fs'); @@ -97,10 +99,16 @@ jobs: - name: Publish with npm trusted publishing if: steps.npm.outputs.published == 'false' - run: npm publish --provenance --access public --tag "$NPM_TAG" + run: | + if [[ "$NPM_TAG" == "next" ]]; then + npm publish --provenance --access public --tag next + else + # Keep npm's implicit-latest guard against publishing an older version. + npm publish --provenance --access public + fi - name: Create GitHub release - uses: actions/github-script@v7 + uses: actions/github-script@v9.0.0 with: script: | const tag = `v${process.env.RELEASE_VERSION}`; From c09a78ea84881a3f3d557cdaa33a0e780dd742fb Mon Sep 17 00:00:00 2001 From: MK Date: Sat, 14 Nov 2026 22:41:58 +0800 Subject: [PATCH 5/5] ci: use major version tags for GitHub actions --- .github/workflows/release.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 756b18f..a34adc7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -17,14 +17,14 @@ jobs: version: ${{ steps.version.outputs.version }} npm_tag: ${{ steps.version.outputs.npm_tag }} steps: - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@v7 with: fetch-depth: 0 persist-credentials: false - name: Compare package versions id: version - uses: actions/github-script@v9.0.0 + uses: actions/github-script@v9 with: script: | const { execFileSync } = require('node:child_process'); @@ -60,12 +60,12 @@ jobs: RELEASE_VERSION: ${{ needs.version.outputs.version }} NPM_TAG: ${{ needs.version.outputs.npm_tag }} steps: - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@v7 with: ref: ${{ github.sha }} persist-credentials: false - - uses: actions/setup-node@v7.1.0 + - uses: actions/setup-node@v7 with: node-version: '24' registry-url: https://registry.npmjs.org @@ -76,7 +76,7 @@ jobs: - name: Check whether the version is already published id: npm - uses: actions/github-script@v9.0.0 + uses: actions/github-script@v9 with: script: | const { readFileSync } = require('node:fs'); @@ -108,7 +108,7 @@ jobs: fi - name: Create GitHub release - uses: actions/github-script@v9.0.0 + uses: actions/github-script@v9 with: script: | const tag = `v${process.env.RELEASE_VERSION}`;