From 57cb118f7e65d302e44827cb27be155327b35db3 Mon Sep 17 00:00:00 2001 From: Sergiu Oala Date: Tue, 8 Sep 2026 08:39:12 +0000 Subject: [PATCH] ci: npm publish workflow --- .github/prerelease-config.json | 11 ++++ .github/prerelease-manifest.json | 3 + .github/release-config.json | 18 ++++++ .github/release-manifest.json | 3 + .github/workflows/npm-publish.yml | 87 ++++++++++++++++++++++++++++ .github/workflows/release-please.yml | 53 +++++++++++++++++ .npmrc | 2 +- README.md | 23 ++++++++ 8 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 .github/prerelease-config.json create mode 100644 .github/prerelease-manifest.json create mode 100644 .github/release-config.json create mode 100644 .github/release-manifest.json create mode 100644 .github/workflows/npm-publish.yml create mode 100644 .github/workflows/release-please.yml diff --git a/.github/prerelease-config.json b/.github/prerelease-config.json new file mode 100644 index 0000000..14cf864 --- /dev/null +++ b/.github/prerelease-config.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "release-type": "node", + "include-component-in-tag": false, + "versioning": "prerelease", + "prerelease": true, + "prerelease-type": "rc", + "packages": { + ".": {} + } +} diff --git a/.github/prerelease-manifest.json b/.github/prerelease-manifest.json new file mode 100644 index 0000000..592b3ad --- /dev/null +++ b/.github/prerelease-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "6.2.2" +} diff --git a/.github/release-config.json b/.github/release-config.json new file mode 100644 index 0000000..0df416e --- /dev/null +++ b/.github/release-config.json @@ -0,0 +1,18 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "release-type": "node", + "include-component-in-tag": false, + "versioning": "default", + "prerelease": false, + "packages": { + ".": { + "extra-files": [ + { + "type": "json", + "path": ".github/prerelease-manifest.json", + "jsonpath": "$[\".\"]" + } + ] + } + } +} diff --git a/.github/release-manifest.json b/.github/release-manifest.json new file mode 100644 index 0000000..592b3ad --- /dev/null +++ b/.github/release-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "6.2.2" +} diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml new file mode 100644 index 0000000..6290ac1 --- /dev/null +++ b/.github/workflows/npm-publish.yml @@ -0,0 +1,87 @@ +name: npm-publish + +on: + workflow_dispatch: + inputs: + tag: + description: >- + Release tag to publish, for example v6.2.2. Leave empty to run + validation only (dry run). + type: string + +permissions: + contents: read + +concurrency: + # tag grouping - queues repeat publishes of the same release + # run_id - fallback for validation-only runs, which have no tag + group: npm-publish-${{ inputs.tag || github.run_id }} + cancel-in-progress: false + +jobs: + validate: + name: Validate + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ inputs.tag || github.ref }} + persist-credentials: false + + - uses: actions/setup-node@v6 + with: + node-version: 22.x + + - name: verify release version + if: inputs.tag != '' + run: | + pkg_name=$(jq -r .name package.json) + pkg_version=$(jq -r .version package.json) + tag_version="${RELEASE_TAG#v}" + if [ "$pkg_version" != "$tag_version" ]; then + echo "package.json version ($pkg_version) does not match release tag ($tag_version)" + exit 1 + fi + if npm view "${pkg_name}@${pkg_version}" version >/dev/null 2>&1; then + echo "${pkg_name}@${pkg_version} is already published" + exit 1 + fi + env: + RELEASE_TAG: ${{ inputs.tag }} + + - name: validate publish package contents + run: | + npm pack --dry-run 2>&1 | tee pack.log + grep -q 'lib/index.js' pack.log + ! grep -qE '[[:space:]]test/' pack.log + ! grep -qE '[[:space:]]tools/' pack.log + + publish: + name: publish + needs: validate + if: inputs.tag != '' + runs-on: ubuntu-latest + environment: Publish + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v7 + with: + ref: ${{ inputs.tag }} + persist-credentials: false + + - uses: actions/setup-node@v6 + with: + node-version: 26.x + registry-url: https://registry.npmjs.org + + - name: npm stage publish + env: + RELEASE_TAG: ${{ inputs.tag }} + run: | + if [[ "$RELEASE_TAG" == *-rc* ]]; then + npm stage publish --provenance --tag rc + else + npm stage publish --provenance + fi diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml new file mode 100644 index 0000000..fe8c2ec --- /dev/null +++ b/.github/workflows/release-please.yml @@ -0,0 +1,53 @@ +on: + push: + branches: + - main +permissions: + contents: write + issues: write + pull-requests: write + # Releases created with GITHUB_TOKEN cannot trigger other workflows, so + # npm-publish is dispatched explicitly below. workflow_dispatch is one of the + # few events that always creates a run, even from GITHUB_TOKEN. + actions: write + +concurrency: + group: release-please-${{ github.ref_name }} + cancel-in-progress: false + +name: release-please +jobs: + release-please: + runs-on: ubuntu-latest + steps: + - uses: googleapis/release-please-action@v5 + id: prerelease + with: + token: ${{ secrets.GITHUB_TOKEN }} + config-file: .github/prerelease-config.json + manifest-file: .github/prerelease-manifest.json + target-branch: ${{ github.ref_name }} + + # Once an RC PR is merged and tagged, replace it with the stable Release + # PR. The stable config also synchronizes the prerelease manifest when + # that stable PR is eventually merged. + - name: create stable Release PR + if: >- + steps.prerelease.outputs.releases_created == 'true' && + contains(steps.prerelease.outputs.tag_name, '-rc') + uses: googleapis/release-please-action@v5 + with: + token: ${{ secrets.GITHUB_TOKEN }} + config-file: .github/release-config.json + manifest-file: .github/release-manifest.json + target-branch: ${{ github.ref_name }} + + # The prerelease action recognizes merges of both RC and stable Release + # PRs. It creates the corresponding tag and GitHub Release in either case. + - name: trigger npm-publish + if: steps.prerelease.outputs.releases_created == 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_REPO: ${{ github.repository }} + TAG: ${{ steps.prerelease.outputs.tag_name }} + run: gh workflow run npm-publish.yml --ref "$GITHUB_REF_NAME" -f tag="$TAG" diff --git a/.npmrc b/.npmrc index 9cf9495..43c97e7 100644 --- a/.npmrc +++ b/.npmrc @@ -1 +1 @@ -package-lock=false \ No newline at end of file +package-lock=false diff --git a/README.md b/README.md index 5a53f16..0e25aa0 100644 --- a/README.md +++ b/README.md @@ -170,3 +170,26 @@ enroute.validate({ } }); ``` + +## Cutting a release + +Releases are automated with [release-please](https://github.com/googleapis/release-please) and published to npm via GitHub Actions. We use [Conventional Commits](http://conventionalcommits.org/) to simplify the process of managing semver on this project — release-please parses commit types (`fix`, `feat`, etc.) to determine the version bump. + +### Release flow + +1. Merge pull requests to `main` using [Conventional Commits](http://conventionalcommits.org/). +2. `release-please` opens or updates a **Release PR** with the version bump and changelog. +3. Review and merge the Release PR when ready to ship. +4. `release-please` creates a GitHub Release and version tag (for example `v6.3.0`). +5. The same `release-please` run then dispatches `npm-publish` with that tag. It re-runs tests, validates the package contents (`npm pack --dry-run`), then pauses at the `Publish` environment for reviewer approval. +6. After approval, the package is published to npm via [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC). + +Release candidates follow the same path: merging an RC PR tags an `-rc` version, `npm-publish` publishes it with `--tag rc`, and `release-please` then opens a stable Release PR. + +### Dry run + +To validate the publish workflow without publishing, run **Actions → npm-publish → Run workflow** and leave `tag` empty. This runs tests and `npm pack --dry-run`, and skips the publish job. + +### Retrying a failed run + +If `npm-publish` fails, use **Re-run jobs** on the failed run itself (Actions tab) — it replays the same tag, so there's no need to cut a new one. You can also re-run **Actions → npm-publish → Run workflow** with the same `tag`. Either is safe even if `publish` partially ran, since `validate` checks whether the version is already on npm before continuing.