fix: single-tag releases - version tags live only on packaged commits

release-please now runs with skip-github-release and owns only the version math, changelog, manifest, and release PR. The repo-owned pipeline detects the release-PR merge (manifest version step + merge subject + PR provenance, refusing ambiguity), builds the bundle, commits it as a child of the merge commit, creates vX.Y.Z once on that child, attests, creates the draft release with the CHANGELOG section as notes, uploads bundle + schema + sigstore assets, force-moves the major with a compare-and-swap, and confirms origin's refs carry the bundle. The release PR itself carries the next last-release-sha boundary (anchored to its merge parent on every refresh), so merging a release also advances release-please's walk boundary - version tags are not on main, so its commit walk cannot find them by tag - with no push to main and no admin credential; a boundary-check job parks release-please loudly if the recorded boundary ever goes stale.

The git topology lives in .github/scripts/release-pipeline.ts, unit-tested against fixture repositories (31 tests: fresh placement, byte-verified idempotent reruns, tamper stops, the PR-carried anchor, boundary freshness, no backward major moves), so tag placement is proven on every push instead of on release day.

The release-tags ruleset drops the retired build/ namespace and gains a repository-admin bypass for deliberate repair; a new major-release-tags ruleset blocks major-tag deletion while leaving moves to the pipeline. Docs, tests, and comments sweep every build/ reference; @vX.Y.Z is the runnable exact pin now.

publish-release is temporarily commented out so the first release under the scheme runs end to end but stays a draft for inspection; publish by hand and uncomment after verifying.

No secret is required: without REPO_PLATFORM_TOKEN the release PR's checks need the usual close/reopen to run, nothing else.

The next release is forced to 2.0.1 (release-as): the first 2.0.1 attempt was cut under the old two-tag scheme and withdrawn before it shipped, so the number is reused for its replacement. Remove release-as after 2.0.1 ships. The managed release-please workflow gains a guard failing loudly when a merged release PR is stuck at autorelease: pending, the state release-please otherwise swallows as a green abort.

Author: Vivswan

.github/scripts/release-pipeline.ts

@@ -129,23 +129,48 @@ rulesets:
         actor_type: RepositoryRole
         bypass_mode: always
 
-  # vX.Y.Z release tags are immutable: template-sync workflow pins and
-  # release artifacts reference them. So are their build/vX.Y.Z packaging
-  # tags, the runnable refs exact pins name; the prefix puts them outside
-  # the v*.*.* pattern, and fnmatch's * does not cross "/", so no single
-  # pattern covers both. The bare moving major tag (v1) is deliberately
-  # NOT matched; the release workflow force-moves it to the latest build
-  # commit.
+  # vX.Y.Z release tags are immutable: each points at a packaged commit (a
+  # child of its release commit carrying the built bundle) that template-
+  # sync workflow pins and release artifacts reference. The release
+  # workflow creates each tag once and never moves it (reruns verify the
+  # existing tag instead); repository admins bypass for deliberate,
+  # auditable repair. The bare moving major tag (v2) is deliberately NOT
+  # matched here - the release workflow force-moves it to the newest
+  # packaged commit in its line - but major-release-tags below still
+  # blocks its deletion.
   - name: release-tags
     target: tag
     enforcement: active
     conditions:
       ref_name:
         include:
           - v*.*.*
-          - build/v*.*.*
         exclude: []
     rules:
       - type: deletion
       - type: non_fast_forward
       - type: update
+    bypass_actors:
+      - actor_id: 5
+        actor_type: RepositoryRole
+        bypass_mode: always
+
+  # The moving major tags (v1, v2) move on purpose - every release in the
+  # line force-pushes them to its packaged commit - so no update rule, but
+  # they must never vanish: a deleted major bricks every @v2 consumer at
+  # once. fnmatch's * crosses dots, so v* also covers the vX.Y.Z tags;
+  # that overlap is a harmless union with release-tags above.
+  - name: major-release-tags
+    target: tag
+    enforcement: active
+    conditions:
+      ref_name:
+        include:
+          - v*
+        exclude: []
+    rules:
+      - type: deletion
+    bypass_actors:
+      - actor_id: 5
+        actor_type: RepositoryRole
+        bypass_mode: always

.github/settings.yml

@@ -0,0 +1,63 @@
+# The release-please chain of the repo-owned pipeline (called by
+# release.yml on every push; see release.yml's header for the single-tag
+# scheme). Order: prove the recorded boundary is fresh, let release-please
+# build or refresh the release PR, then anchor the NEXT boundary into that
+# PR's branch - merging the release PR advances last-release-sha on main
+# as part of the release itself, so nothing ever pushes to main and no
+# admin credential is involved.
+
+name: Release bookkeeping
+
+on:
+  workflow_call:
+
+jobs:
+  # last-release-sha must be the newest release merge on main or its
+  # parent; anything else means a boundary was lost (or a release merge
+  # slipped past detection) and every release PR refresh would be computed
+  # from a stale one - park release-please loudly instead.
+  boundary-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The newest release merge can be arbitrarily far behind HEAD.
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - name: Confirm last-release-sha matches the newest release merge
+        run: bun .github/scripts/release-pipeline.ts boundary-check
+
+  # Version math, changelog, manifest, and the release PR - never tags or
+  # releases (skip-github-release); the managed workflow itself also gates
+  # on no merged release PR being stuck at "autorelease: pending".
+  release-please:
+    needs: [boundary-check]
+    uses: ./.github/workflows/release-please.yml
+    secrets: inherit
+
+  # Write the next boundary INTO the release PR: last-release-sha becomes
+  # main's current head - the future merge commit's parent, which is just
+  # as good a boundary (the walk then also collects the merge itself, a
+  # chore the changelog hides). The release-freshness gate keeps the value
+  # exact: a release PR must contain main's tip to merge, and every
+  # refresh re-anchors. The branch is unprotected, so the default token
+  # pushes it; without REPO_PLATFORM_TOKEN the PR's checks need the usual
+  # close/reopen to run either way.
+  anchor-release-pr:
+    needs: [release-please]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - name: Anchor the boundary inside the release PR branch
+        run: bun .github/scripts/release-pipeline.ts anchor

.github/workflows/release-bookkeeping.yml

@@ -77,6 +77,27 @@ jobs:
           tracking-labels: "fuzz-nightly,nightly-failure"
         env:
           GH_TOKEN: ${{ github.token }}
+      # release-please silently ABORTS - green - when any merged release PR
+      # still wears "autorelease: pending" ("untagged, merged release PRs
+      # outstanding"): release PRs stop being proposed with no red anywhere.
+      # Gate the action on that state being clean. A fresh merge is exempt
+      # (its label is legitimately pending until the pipeline tags or
+      # publishes it, which can happen in a parallel job), so only a
+      # pending label older than 30 minutes fails.
+      - name: Fail when a stale pending release PR parks release-please
+        if: steps.head.outputs.current == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          cutoff="$(date -u -d '30 minutes ago' +%Y-%m-%dT%H:%M:%SZ)"
+          stale="$(gh pr list --state merged --label 'autorelease: pending' \
+            --json number,mergedAt \
+            --jq "[.[] | select(.mergedAt < \"$cutoff\") | .number] | join(\", \")")"
+          if [ -n "$stale" ]; then
+            echo "::error::merged release PR(s) #$stale have worn 'autorelease: pending' for over 30 minutes, so release-please refuses to propose any new release ('untagged, merged release PRs outstanding'). Finish or abandon that release, then move the label to 'autorelease: tagged'."
+            exit 1
+          fi
       - uses: googleapis/release-please-action@v5
         id: release
         if: steps.head.outputs.current == 'true'

.github/workflows/release-please.yml

@@ -0,0 +1,163 @@
+# The release chain of the repo-owned pipeline (called by release.yml with
+# the tag/version its detection proved; see release.yml's header for the
+# single-tag scheme). Packages the merge commit, creates the version tag on
+# the packaged child, attests, releases draft-first, moves the major, and
+# publishes last.
+
+name: Release publish
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: The vX.Y.Z tag to create for this release
+        required: true
+        type: string
+      version:
+        description: The X.Y.Z version (names the CHANGELOG.md section)
+        required: true
+        type: string
+
+jobs:
+  package-release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write # tag pushes; also what makes the draft visible to gh
+      id-token: write # OIDC identity for the provenance attestation
+      attestations: write
+      # The release-health gate reads open issues, the release PR's
+      # override label, and Dependabot alerts; a permissions block zeroes
+      # everything it omits, so the gate's read scopes must be spelled out.
+      issues: read
+      pull-requests: read
+      vulnerability-alerts: read
+    steps:
+      - uses: actions/checkout@v7
+      # Authoritative release gating, the same action the managed
+      # release-please.yml runs: the release PR's own release-health check
+      # can be stale by merge time (a tracking or blocker issue opened
+      # after it went green re-runs no check), so re-check here before
+      # anything is tagged.
+      - uses: Vivswan/repo-platform/actions/release-health@main
+        with:
+          mode: release
+          tracking-labels: "fuzz-nightly,nightly-failure"
+        env:
+          GH_TOKEN: ${{ github.token }}
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - name: Build the bundle and the schema
+        run: |
+          bun install --frozen-lockfile --ignore-scripts
+          bun run build
+          # The uploaded schema asset and the raw URLs at the version and
+          # major tags must serve the bytes committed at the merge commit;
+          # a divergent regeneration (generator drift, or a compromised
+          # generator - SECURITY.md leans on this) stops the release here.
+          git diff --exit-code lib/settings.schema.json
+      # Create the packaged child and its version tag exactly once; a rerun
+      # byte-verifies the existing tag instead (parent, whole tree, bundle
+      # bytes) and never moves it. Both paths end with the worktree bundle
+      # equal to the tagged bundle, which is what the attestation signs.
+      - name: Create or verify the packaged commit and its version tag
+        env:
+          TAG: ${{ inputs.tag }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: bun .github/scripts/release-pipeline.ts package
+      - name: Attest build provenance for the bundle
+        id: attest
+        uses: actions/attest-build-provenance@v4
+        with:
+          subject-path: lib/index.js
+      # gh names assets after the file, so the attestation bundle is copied
+      # to a stable, self-describing name for offline verification:
+      #   gh attestation verify lib/index.js --bundle <asset> -R <owner>/<repo>
+      - name: Create the draft release and upload the packaged artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ inputs.tag }}
+          VERSION: ${{ inputs.version }}
+          ATTESTATION_BUNDLE: ${{ steps.attest.outputs.bundle-path }}
+        run: |
+          # A missing release and a transport error both leave state empty;
+          # on a transport error the create below then fails loudly with
+          # "already exists" instead of silently skipping the upload.
+          state="$(gh release view "$TAG" --json isDraft --jq .isDraft 2>/dev/null || true)"
+          if [ -z "$state" ]; then
+            bun .github/scripts/release-pipeline.ts notes "$VERSION" > "$RUNNER_TEMP/notes.md"
+            gh release create "$TAG" --draft --verify-tag --title "$TAG" \
+              --notes-file "$RUNNER_TEMP/notes.md"
+          elif [ "$state" = "false" ]; then
+            echo "::notice::release $TAG is already published; skipping the asset upload (published releases freeze their assets)"
+            exit 0
+          fi
+          cp "$ATTESTATION_BUNDLE" "$RUNNER_TEMP/lib-index-js.sigstore.json"
+          gh release upload "$TAG" lib/settings.schema.json lib/index.js \
+            "$RUNNER_TEMP/lib-index-js.sigstore.json" --clobber
+      # Move the moving major tag (v2 for a v2.x.y release) to the packaged
+      # commit, re-verified against origin from scratch: major-pinned
+      # consumers must never receive an unpackaged commit, a package of the
+      # wrong source, or (on a rerun of an old release's job) a step
+      # backward to an older release.
+      - name: Move the major tag to the packaged commit
+        env:
+          TAG: ${{ inputs.tag }}
+        run: bun .github/scripts/release-pipeline.ts retag-major
+
+  # The gate between packaging and publishing, against origin's ACTUAL
+  # state rather than anything the packaging run held locally: the version
+  # tag and the major must both point at the packaged child of this merge
+  # commit, and that commit's tree must carry a non-empty lib/index.js.
+  verify-release:
+    needs: [package-release]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - name: Confirm the published refs carry the bundle
+        env:
+          TAG: ${{ inputs.tag }}
+        run: bun .github/scripts/release-pipeline.ts verify
+
+# Publish last: published releases freeze their assets, so every job that
+# mutates the release must sit in this needs list. Also flips the release
+# PR's autorelease label, which release-please no longer flips itself
+# under skip-github-release.
+#
+# COMMENTED OUT for the first single-tag release: the pipeline runs end
+# to end (tag, attest, draft, assets, major) but leaves the release a
+# DRAFT for inspection. After verifying, publish by hand
+# (gh release edit <tag> --draft=false) and uncomment this job.
+# publish-release:
+#   needs: [package-release, verify-release]
+#   runs-on: ubuntu-latest
+#   timeout-minutes: 5
+#   permissions:
+#     contents: write
+#     pull-requests: write
+#   steps:
+#     - name: Publish the GitHub release
+#       env:
+#         GH_TOKEN: ${{ secrets.REPO_PLATFORM_TOKEN || github.token }}
+#         GH_REPO: ${{ github.repository }}
+#         TAG: ${{ inputs.tag }}
+#       run: gh release edit "$TAG" --draft=false
+#     - name: Mark the release PR tagged
+#       env:
+#         GH_TOKEN: ${{ github.token }}
+#         GH_REPO: ${{ github.repository }}
+#       run: |
+#         number="$(gh api "repos/$GH_REPO/commits/$GITHUB_SHA/pulls" --jq '.[0].number // empty')"
+#         if [ -z "$number" ]; then
+#           echo "::notice::no pull request found for $GITHUB_SHA; leaving the autorelease labels alone"
+#           exit 0
+#         fi
+#         gh api -X DELETE "repos/$GH_REPO/issues/$number/labels/autorelease%3A%20pending" || true
+#         gh api "repos/$GH_REPO/issues/$number/labels" -f "labels[]=autorelease: tagged"