diff --git a/.github/workflows/daily-release.yml b/.github/workflows/daily-release.yml index 6fc4f5ec..1ce1faf0 100644 --- a/.github/workflows/daily-release.yml +++ b/.github/workflows/daily-release.yml @@ -540,9 +540,13 @@ jobs: tag: name: tag the merged release and dispatch the publish run - # Inverted mirror of the release job: a scheduled or manual run must never - # tag, and only a push to `main` can carry a merged release. - if: github.event_name == 'push' + # A push to `main` carries a merged release; the scheduled slot also comes + # here, because a release can be left half-made with no further push (the tag + # written, the publish dispatch failed, #866). The job is idempotent: it + # creates the tag only when it is missing, dispatches only when the tag exists + # without its GitHub Release, and is a no-op when both exist. The manual + # dispatch never reaches it, so a dry run cannot tag anything. + if: github.event_name == 'push' || github.event_name == 'schedule' runs-on: ubuntu-latest timeout-minutes: 10 permissions: @@ -557,30 +561,75 @@ jobs: node-version: 22 - name: Collect the pushed commit + id: collect env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | set -euo pipefail REPO="$GITHUB_REPOSITORY" - SHA="$GITHUB_SHA" + # The version first, because it is the only fact a scheduled run has + # before it knows which release it is repairing. + gh api "repos/${REPO}/contents/package.json?ref=${GITHUB_SHA}" --jq '.content' | base64 -d | jq -r '.version // empty' > "$RUNNER_TEMP/version.txt" + VERSION="$(cat "$RUNNER_TEMP/version.txt")" + # #866: on `schedule`, $GITHUB_SHA is main's tip, and the identity check + # needs the release pull request's squash commit. One merge after the + # release makes those differ, so a scheduled run could never repair the + # release it names. The target is resolved by the tested helper: the + # event's own commit on a push, the merged `release: v` pull + # request's merge commit on a schedule. An unresolvable shape keeps the + # tip, and the identity check then refuses it with its own reason. + gh pr list --repo "$REPO" --state merged --limit 50 \ + --search "v${VERSION} in:title" \ + --json number,title,mergeCommit,headRefName > "$RUNNER_TEMP/release-prs.json" + TARGET="$(VERSION="$VERSION" node --input-type=module -e ' + import { readFileSync } from "node:fs" + import { resolveTarget } from "./scripts/lib/release-tag.mjs" + const TMP = process.env.RUNNER_TEMP ?? "/tmp" + const target = resolveTarget({ + eventName: process.env.GITHUB_EVENT_NAME, + sha: process.env.GITHUB_SHA, + version: process.env.VERSION, + releasePrs: JSON.parse(readFileSync(TMP + "/release-prs.json", "utf8")), + }) + console.error(`target ${target.sha} — ${target.reason}`) + process.stdout.write(target.sha) + ')" + echo "sha=${TARGET}" >> "$GITHUB_OUTPUT" + echo "read version ${VERSION} at ${TARGET} from the ${GITHUB_EVENT_NAME} event" >> "$GITHUB_STEP_SUMMARY" # The pull requests that produced this commit, and the tag list as the # API sees it — not the runner's copy, which is one commit deep. - gh api "repos/${REPO}/commits/${SHA}/pulls" > "$RUNNER_TEMP/pulls.json" + gh api "repos/${REPO}/commits/${TARGET}/pulls" > "$RUNNER_TEMP/pulls.json" gh api --paginate "repos/${REPO}/git/matching-refs/tags/v" \ | jq -s 'flatten | map(.ref) | map(ltrimstr("refs/tags/"))' > "$RUNNER_TEMP/tags.json" - gh api "repos/${REPO}/contents/package.json?ref=${SHA}" --jq '.content' | base64 -d | jq -r '.version // empty' > "$RUNNER_TEMP/version.txt" - echo "read version $(cat "$RUNNER_TEMP/version.txt") at ${SHA}" >> "$GITHUB_STEP_SUMMARY" + # #866: the tag and the GitHub Release are two different writes, and the + # decision has to tell "tag exists, release missing" from "both exist". + # A 404 is the normal "not released yet" answer and is recorded as `{}`; + # anything else is an unreadable fact, and a blind `publish` on an + # unreadable fact would dispatch a second publish run, so it fails here + # as the single report instead. + RELEASE_TAG="v$(cat "$RUNNER_TEMP/version.txt")" + if gh api "repos/${REPO}/releases/tags/${RELEASE_TAG}" > "$RUNNER_TEMP/release.json" 2> "$RUNNER_TEMP/release.err"; then + echo "GitHub Release ${RELEASE_TAG} exists" >> "$GITHUB_STEP_SUMMARY" + elif grep -q 'HTTP 404' "$RUNNER_TEMP/release.err"; then + printf '{}\n' > "$RUNNER_TEMP/release.json" + echo "no GitHub Release for ${RELEASE_TAG}" >> "$GITHUB_STEP_SUMMARY" + else + echo "::error::could not read the GitHub Release state for ${RELEASE_TAG}: $(head -c 300 "$RUNNER_TEMP/release.err")" + exit 1 + fi - name: Decide the tag id: decide env: - SHA: ${{ github.sha }} + SHA: ${{ steps.collect.outputs.sha }} run: | set -euo pipefail VERSION="$(cat "$RUNNER_TEMP/version.txt")" export VERSION SHA - # Whether this push is the squash of the mechanical release is a pure - # decision with a test per refusal, in scripts/lib/release-tag.mjs. + # Whether this commit is the squash of the mechanical release is a pure + # decision with a test per refusal, in scripts/lib/release-tag.mjs. It + # answers `create` (tag missing), `publish` (tag exists, its GitHub + # Release does not) or `skip` (both exist, or this is not the release). node --input-type=module -e ' import { readFileSync, appendFileSync } from "node:fs" import { plan } from "./scripts/lib/release-tag.mjs" @@ -588,6 +637,7 @@ jobs: const result = plan({ pulls: JSON.parse(readFileSync(TMP + "/pulls.json", "utf8")), tags: JSON.parse(readFileSync(TMP + "/tags.json", "utf8")), + release: JSON.parse(readFileSync(TMP + "/release.json", "utf8")), packageVersion: process.env.VERSION, sha: process.env.SHA, }) @@ -614,7 +664,10 @@ jobs: echo "created ${TAG} on ${SHA}" >> "$GITHUB_STEP_SUMMARY" - name: Dispatch release.yml at the tag - if: ${{ steps.decide.outputs.action == 'create' }} + # #866: `publish` means the tag was written but its GitHub Release was + # not, so the owed write is the dispatch alone. Gating it on `create` was + # what wedged a release after one failed dispatch. + if: ${{ steps.decide.outputs.action == 'create' || steps.decide.outputs.action == 'publish' }} env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} TAG: ${{ steps.decide.outputs.tag }} @@ -622,6 +675,8 @@ jobs: set -euo pipefail # A tag written with the automatic token starts no workflow, so the # publish run is dispatched explicitly at that tag. release.yml verifies - # the tag is an ancestor of main before it publishes anything. + # the tag is an ancestor of main before it publishes anything, so a + # repeated dispatch after a failed one is safe: a complete release is + # refused there, not published twice. gh workflow run release.yml --ref "$TAG" -f "tag=$TAG" echo "dispatched release.yml at ${TAG}" >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 430c81e7..c2617ced 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -132,11 +132,34 @@ jobs: REPO: ${{ github.repository }} run: echo "IMAGE=ghcr.io/${REPO,,}" >> "$GITHUB_ENV" + # #866: a release is two writes, and the second one used to repeat itself. + # The tag job dispatches this workflow when a tag exists without its GitHub + # Release, and before this guard the run rebuilt and repushed the image and + # rewrote the notes first — a second dispatch of one tag republished that + # tag's image. The guard answers before anything is built: an existing + # GitHub Release ends the run here, and every step that would write is gated + # on `published != 'true'`. + - name: Stop when the release already exists + id: guard + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + RELEASE_TAG: ${{ inputs.tag || github.ref_name }} + run: | + set -euo pipefail + if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then + echo "published=true" >> "$GITHUB_OUTPUT" + echo "${RELEASE_TAG} already has a GitHub Release; nothing is built or published" >> "$GITHUB_STEP_SUMMARY" + else + echo "published=false" >> "$GITHUB_OUTPUT" + echo "${RELEASE_TAG} has no GitHub Release yet; publishing" >> "$GITHUB_STEP_SUMMARY" + fi + # #183: stamp the image so /healthz on the published tag names the commit # it was cut from. The tag checkout is not necessarily github.sha, so the # commit comes from the checked-out tree, the same way docs/deploy.md # tells an operator to stamp a local build. - name: Build the image + if: ${{ steps.guard.outputs.published != 'true' }} env: RELEASE_TAG: ${{ inputs.tag || github.ref_name }} run: | @@ -150,6 +173,7 @@ jobs: # after the push; without it the provenance step silently has nothing to # attest. - name: Publish to GHCR + if: ${{ steps.guard.outputs.published != 'true' }} id: push env: GHCR_USER: ${{ github.actor }} @@ -168,6 +192,7 @@ jobs: echo "digest=$digest" >> "$GITHUB_OUTPUT" - name: Generate an SBOM for the published image + if: ${{ steps.guard.outputs.published != 'true' }} uses: anchore/sbom-action@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c # v0.24.3 with: image: ${{ env.IMAGE }}:${{ env.RELEASE_TAG }} @@ -178,6 +203,7 @@ jobs: registry-password: ${{ secrets.GITHUB_TOKEN }} - name: Attest the image provenance + if: ${{ steps.guard.outputs.published != 'true' }} uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 with: subject-name: ${{ env.IMAGE }} @@ -192,6 +218,7 @@ jobs: # trusting a workflow run nobody opened. Written before the Release exists, # so a run that fails earlier never leaves a body claiming them. - name: Record the published chain in the release notes + if: ${{ steps.guard.outputs.published != 'true' }} env: RELEASE_TAG: ${{ inputs.tag || github.ref_name }} DIGEST: ${{ steps.push.outputs.digest }} @@ -205,6 +232,7 @@ jobs: } >> /tmp/release-notes.md - name: Create or update the GitHub release + if: ${{ steps.guard.outputs.published != 'true' }} env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} RELEASE_TAG: ${{ inputs.tag || github.ref_name }} diff --git a/changelog.d/866-finish-half-made-release.fixed.md b/changelog.d/866-finish-half-made-release.fixed.md new file mode 100644 index 00000000..4ffe1db7 --- /dev/null +++ b/changelog.d/866-finish-half-made-release.fixed.md @@ -0,0 +1 @@ +A release that was left half-made is now finished by the routine instead of by a human: when the tag exists but its GitHub Release does not, the tag job dispatches the publish run instead of skipping, and the scheduled slot repairs a merged release pull request whose tag is still missing. A tag that already has its release stays a no-op, a publish run that finds that release in place stops before it builds an image, and only the squash of the merged release pull request can trigger either write. diff --git a/docs/deploy.md b/docs/deploy.md index 2ec58258..fefa7bc1 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -498,6 +498,51 @@ two-parent check would refuse every real release. Not in this slice: no signed-commit requirement (a non-goal on the card) and no change to the release cadence or the tag name. +### Finishing a half-made release (#866) + +A release is two write moments: the annotated tag, then the publish run +dispatched at it. When the dispatch failed after the tag was written, the tag job +used to answer `skip` on every later run — the tag existed, so nothing was owed — +and the release stayed at `not released` until a human re-dispatched it. + +The tag job now decides from three API facts (`scripts/lib/release-tag.mjs`, one +test per row): + +| tag | GitHub Release | action | +|---|---|---| +| missing | — | `create` the tag on the release pull request's squash commit | +| present | missing | `publish`: dispatch `release.yml` at the existing tag, write no tag | +| present | present | `skip`: nothing to publish | + +`publish` is gated by the same identity check as `create`: the commit must be the +squash of the merged `release: v` pull request from `release/v`, +so an ordinary push to `main` cannot re-dispatch a release it did not produce. +`release.yml` re-verifies the tag before publishing, and it asks one question +before it builds anything: if a GitHub Release already exists for the tag, the run +records `published` in `Stop when the release already exists` and every step that +would write is gated on that answer. A repeated dispatch of a complete release +therefore cannot rebuild and repush the image or rewrite its notes — the claim is +the step, not a sentence here. + +The job still runs on the `push` that merges the release pull request, and it now +also runs on the scheduled slot: a tag without its release, or a merged release +pull request without a tag, is repaired by the next daily run instead of waiting +for someone to notice. A scheduled run acts on the merge commit of the merged +`release: v` pull request rather than on `main`'s tip, because after any +later merge the tip is no longer that merge and the identity check would correctly +refuse it; a scheduled run that cannot name exactly one such pull request keeps +the tip, and the identity check then refuses it with its own reason rather than +guessing a release to repair. The release job's drive still reports `tag` (a merged +release pull request with no tag) — that is the night's summary line, not the +writer. **The tag job is the only tag writer**: the release job never creates a +tag, and its `tag` action is documented here rather than executed. + +Two recovery steps remain owner actions, unchanged by this slice: an orphan +`release/vX.Y.Z` branch still cannot be deleted through the `keep release +branches` ruleset (`bypass_actors: []`), and relaxing that is a ruleset edit, not +a commit. The runbook is still: delete or adopt the branch after adding the +identity to the ruleset bypass, then let the next run tag the merge. + ### Automatic tag deployment and verification The release plan → release pull request → tag half lives in diff --git a/scripts/lib/release-tag.d.mts b/scripts/lib/release-tag.d.mts index f20a26c6..964d2a6c 100644 --- a/scripts/lib/release-tag.d.mts +++ b/scripts/lib/release-tag.d.mts @@ -13,9 +13,17 @@ export interface ReleaseTagPr { head?: ReleaseTagPrHead | null } +export interface ReleaseTagRelease { + /** `tag_name` on `GET /releases/tags/{tag}`; `tag` is accepted for fixtures. */ + tag_name?: string | null + tag?: string | null +} + export interface ReleaseTagInput { pulls?: ReleaseTagPr[] | null tags?: string[] | null + /** The GitHub Release for this version, or `{}`/null when there is none. */ + release?: ReleaseTagRelease | null packageVersion?: string | null sha?: string | null } @@ -23,8 +31,33 @@ export interface ReleaseTagInput { export interface ReleaseTagPlan { tag: string | null sha: string | null - action: 'create' | 'skip' + action: 'create' | 'publish' | 'skip' reason: string } export function plan(input?: ReleaseTagInput): ReleaseTagPlan + +export interface ReleaseTagPrCandidate { + number?: number | null + title?: string | null + /** `gh pr list --json mergeCommit` shape; `merge_commit_sha` is accepted too. */ + mergeCommit?: { oid?: string | null } | null + merge_commit_sha?: string | null +} + +export interface ReleaseTargetInput { + /** `push`, `schedule` or the event that woke the job. */ + eventName?: string | null + /** The event's own commit; `main`'s tip on a scheduled run. */ + sha?: string | null + version?: string | null + releasePrs?: ReleaseTagPrCandidate[] | null +} + +export interface ReleaseTarget { + sha: string + source: 'event' | 'release-merge' + reason: string +} + +export function resolveTarget(input?: ReleaseTargetInput): ReleaseTarget diff --git a/scripts/lib/release-tag.mjs b/scripts/lib/release-tag.mjs index 39a46728..a81638fb 100644 --- a/scripts/lib/release-tag.mjs +++ b/scripts/lib/release-tag.mjs @@ -1,11 +1,26 @@ -// Recognise the merged release pull request behind a push to `main` (issue #80). +// Recognise the merged release pull request behind a push to `main` (issue #80), +// and finish the release when only half of it was made (#866). // -// Pure: no clock, no network, no repository. The tag job collects two API -// payloads — `GET /commits/{sha}/pulls` and `GET /git/matching-refs/tags/v` — and -// this function decides whether that push is the squash of the mechanical release -// pull request and whether the tag for it is still missing. Anything ambiguous -// returns `skip` with a reason: a tag is a published name, so not tagging is the -// recoverable mistake and guessing is not. +// Pure: no clock, no network, no repository. The tag job collects the API +// payloads — `GET /commits/{sha}/pulls`, `GET /git/matching-refs/tags/v` and the +// GitHub Release for `v` — and this function decides +// whether the commit is the squash of the mechanical release pull request and +// which write, if any, is still owed. +// +// A release has two independent write moments: the tag, and the publish run +// dispatched at it. The tag job used to stop at "the tag exists", so a dispatch +// that failed after the tag was created could never be retried — the tag was +// there, every later run answered `skip`, and no GitHub Release, image or SBOM +// was ever produced. The decisions below keep the two apart: +// +// create the tag is missing: create it on the squash commit +// publish the tag exists but its GitHub Release does not: dispatch the +// publish run at the existing tag, and write no tag +// skip nothing is owed, or the commit is not the release merge, or a fact +// needed to act is unreadable +// +// Anything ambiguous returns `skip` with a reason: a tag is a published name, so +// not tagging is the recoverable mistake and guessing is not. const VERSION = /^(\d+)\.(\d+)\.(\d+)$/ const COMMIT = /^[0-9a-f]{40}$/ @@ -33,7 +48,50 @@ function releasePrOf(pulls, version) { return { kind: 'one', pr: candidates[0] } } -export function plan({ pulls, tags, packageVersion, sha } = {}) { +// #866, the scheduled half: on `schedule` the event's commit is `main`'s tip, +// and `plan()` below requires that commit to be the release pull request's squash +// commit. A merge that lands after the release merge makes the tip a different +// commit, so a scheduled run judged the tip, answered `skip`, and the half-made +// release stayed half-made for as long as main kept moving. The commit the tag +// job is allowed to act on is the merged release pull request's merge commit, and +// that is what a scheduled run resolves. A push keeps the commit that was pushed: +// that push is the release merge itself, and resolving anything else there would +// let a later push act on an older release. +// +// Every unresolvable shape keeps the event's commit, so the identity check in +// `plan()` refuses it with its own reason instead of this function choosing a +// commit to act on. +export function resolveTarget({ eventName, sha, version, releasePrs } = {}) { + const commit = String(sha ?? '') + if (eventName !== 'schedule') { + return { sha: commit, source: 'event', reason: `the ${String(eventName ?? 'push')} event's commit ${commit}` } + } + const name = String(version ?? '') + if (!VERSION.test(name)) { + return { sha: commit, source: 'event', reason: `no readable version, so no release pull request to resolve; the target stays ${commit}` } + } + const wanted = `release: v${name}` + const candidates = (Array.isArray(releasePrs) ? releasePrs : []).filter((pr) => String(pr?.title ?? '') === wanted) + if (candidates.length !== 1) { + return { + sha: commit, + source: 'event', + reason: `no single merged pull request titled ${wanted} (${String(candidates.length)} found); the target stays ${commit}`, + } + } + const pr = candidates[0] + const merge = String(pr?.mergeCommit?.oid ?? pr?.merge_commit_sha ?? '') + if (!COMMIT.test(merge)) { + return { sha: commit, source: 'event', reason: `pull request #${String(Number(pr?.number ?? 0))} has no readable merge commit; the target stays ${commit}` } + } + return { + sha: merge, + source: 'release-merge', + reason: `the merged pull request #${String(Number(pr?.number ?? 0))} (${wanted}) produced ${merge}`, + } +} + +export function plan({ pulls, tags, release, packageVersion, sha } = {}) { const commit = String(sha ?? '') if (!COMMIT.test(commit)) { return skip(null, commit, `"${commit}" is not a 40-character sha; a short sha is refused, never resolved`) @@ -43,9 +101,11 @@ export function plan({ pulls, tags, packageVersion, sha } = {}) { return skip(null, commit, `package.json at ${commit} has no readable version; refusing to guess the tag name`) } const tag = `v${version}` - const existing = (Array.isArray(tags) ? tags : []).map(tagName) - if (existing.includes(tag)) return skip(tag, commit, `${tag} already exists; a tag is created once`) + // The identity comes first, and it gates both writes: only the squash of the + // mechanical release pull request may create a tag, and only it may re-dispatch + // a publish run. A later ordinary push to `main` that happens to match the + // paths filter is not the release merge, so it cannot act on the same tag. const found = releasePrOf(pulls, version) if (found.kind !== 'one') return skip(tag, commit, found.reason) const pr = found.pr @@ -66,6 +126,21 @@ export function plan({ pulls, tags, packageVersion, sha } = {}) { return skip(tag, commit, `pull request #${String(number)} does not come from release/v${version} (${branch === '' ? 'no branch' : branch})`) } + const existing = (Array.isArray(tags) ? tags : []).map(tagName) + if (existing.includes(tag)) { + // The half-made release (#866): the tag is written, the publish run is not. + // A GitHub Release carrying this tag means the chain completed, and a second + // dispatch would publish twice. + const published = String(release?.tag_name ?? release?.tag ?? '') === tag + if (published) return skip(tag, commit, `${tag} and its GitHub Release both exist; nothing to publish`) + return { + tag, + sha: commit, + action: 'publish', + reason: `tag ${tag} exists on ${commit} but its GitHub Release does not; dispatching the publish run at the tag`, + } + } + return { tag, sha: commit, diff --git a/test/dailyRelease.test.ts b/test/dailyRelease.test.ts index 2d94e971..2caee632 100644 --- a/test/dailyRelease.test.ts +++ b/test/dailyRelease.test.ts @@ -128,7 +128,17 @@ test('the release job runs on a push too, and the trigger predicate decides whet // the trigger decided, so an ordinary merge that plans nothing is still // visible in the run history. assert.match(job('release'), /if: github\.event_name == 'schedule' \|\| github\.event_name == 'workflow_dispatch' \|\| github\.event_name == 'push'/) - assert.match(job('tag'), /if: github\.event_name == 'push'/) + // #866: the scheduled slot also reaches the tag job, because a release can be + // left half-made with no further push. The job decides from the API state + // (tag present? release present?), not from the event that woke it. + assert.match(job('tag'), /if: github\.event_name == 'push' \|\| github\.event_name == 'schedule'/) + assert.doesNotMatch(job('tag'), /workflow_dispatch/, 'a manual dispatch never tags, so a dry run cannot publish') + assert.match(job('tag'), /releases\/tags\/\$\{RELEASE_TAG\}/, 'the tag job reads whether the GitHub Release exists') + assert.match(job('tag'), /release: JSON\.parse/, 'the release state is an input to the pure decision') + const dispatchStep = between(' - name: Dispatch release.yml at the tag', '') + assert.match(dispatchStep, /steps\.decide\.outputs\.action == 'create' \|\| steps\.decide\.outputs\.action == 'publish'/, 'a tag without its release dispatches the publish run') + const createStep = between(' - name: Create the annotated tag on the merge commit', ' - name: Dispatch release.yml at the tag') + assert.match(createStep, /if: \$\{\{ steps\.decide\.outputs\.action == 'create' \}\}/, 'a publish never writes a second tag') const step = between(' - name: Trigger', ' - name: Check the opener precondition') assert.match(step, /id: trigger/) // #548: this was `always()`. The step reads the state the collect step wrote, @@ -419,3 +429,19 @@ test('release.yml keeps its own concurrency and verifies the tag before publishi assert.match(release, /tag:\s*\n\s*description:/) assert.match(release, /gh release create "\$RELEASE_TAG"/) }) + +test('the scheduled slot resolves the release merge instead of the tip', () => { + // #866: on `schedule` $GITHUB_SHA is main's tip, and the identity check needs + // the release pull request's squash commit. A later merge makes those differ, + // so the scheduled repair never reached the half-made release. The collect step + // resolves the target through the tested helper and publishes it as an output, + // and the decision is made about that target — not about the tip. + const collect = between(' - name: Collect the pushed commit', ' - name: Decide the tag') + assert.match(collect, /id: collect/, 'the collected sha is an output the decide step reads') + assert.match(collect, /import \{ resolveTarget \} from "\.\/scripts\/lib\/release-tag\.mjs"/, 'the scheduled target is a tested pure decision, not assembled in shell') + assert.match(collect, /gh pr list[^\n]*--state merged/, 'the merged release pull request is what names the target') + assert.match(collect, /sha=\$\{TARGET\}/, 'the resolved target is published as the step output') + const decide = between(' - name: Decide the tag', ' - name: Create the annotated tag') + assert.match(decide, /SHA: \$\{\{ steps\.collect\.outputs\.sha \}\}/, 'the decision is made about the resolved target') + assert.equal(decide.includes('github.sha'), false, 'the decide step no longer judges the tip on a scheduled run') +}) diff --git a/test/releasePublishGuard.test.ts b/test/releasePublishGuard.test.ts new file mode 100644 index 00000000..dc665969 --- /dev/null +++ b/test/releasePublishGuard.test.ts @@ -0,0 +1,131 @@ +import test from 'node:test' +import assert from 'node:assert/strict' +import { spawnSync } from 'node:child_process' +import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' + +// #866: a release is two writes, and the second one used to repeat itself. The +// tag job dispatches `release.yml` at a tag whose GitHub Release is missing, but +// `release.yml` was create-*or-update* and rebuilt and repushed the image before +// it looked — so a second dispatch of one tag republished that image and rewrote +// its notes. The claim in the docs is only true with a guard that runs before the +// build, which is the step this file drives: a release that already exists ends +// the run before the image is built, and every step that would write is gated on +// that answer. + +const release = readFileSync('.github/workflows/release.yml', 'utf8') +const GUARD = 'Stop when the release already exists' +const GATE = "steps.guard.outputs.published != 'true'" + +function stepBlocks(workflow: string): string[] { + const start = workflow.indexOf(' steps:\n') + assert.notEqual(start, -1, 'release.yml has a steps list') + return workflow + .slice(start + ' steps:\n'.length) + .split(/\n - /) + .map((block, index) => (index === 0 ? block : `- ${block}`)) + .filter((block) => block.trim() !== '') +} + +function stepName(block: string): string { + const named = /^- name: (.+)$/m.exec(block.replace(/^ /m, '')) + if (named !== null) return String(named[1]).trim() + const uses = /uses: ([^\s#]+)/.exec(block) + if (uses !== null) return `uses ${String(uses[1])}` + const run = /run: ([^\n]+)/.exec(block) + if (run !== null) return `run ${String(run[1]).trim()}` + return block.split('\n')[0] ?? '' +} + +function runBody(block: string): string { + const marker = ' run: |\n' + const start = block.indexOf(marker) + assert.notEqual(start, -1, `step "${stepName(block)}" has a run body`) + const body: string[] = [] + for (const line of block.slice(start + marker.length).split('\n')) { + // The block handed in runs up to the next step, so the first line indented + // less than a body line (` #` for the next step) ends the body. + if (line !== '' && !line.startsWith(' ')) break + body.push(line.startsWith(' ') ? line.slice(10) : line) + } + return body.join('\n') +} + +function guardBlock(): string { + const block = stepBlocks(release).find((candidate) => stepName(candidate) === GUARD) + assert.ok(block !== undefined, `release.yml declares the step "${GUARD}"`) + return block +} + +interface GuardRun { + status: number | null + output: string + summary: string +} + +function runGuard(ghStatus: number): GuardRun { + const dir = mkdtempSync(join(tmpdir(), 'release-guard-')) + try { + const bin = join(dir, 'bin') + mkdirSync(bin) + const gh = join(bin, 'gh') + writeFileSync(gh, `#!/usr/bin/env bash\nexit ${String(ghStatus)}\n`) + chmodSync(gh, 0o755) + const output = join(dir, 'output') + const summary = join(dir, 'summary.md') + writeFileSync(output, '') + writeFileSync(summary, '') + const result = spawnSync('bash', ['-c', runBody(guardBlock())], { + encoding: 'utf8', + env: { + ...process.env, + PATH: `${bin}:${process.env.PATH ?? ''}`, + GITHUB_OUTPUT: output, + GITHUB_STEP_SUMMARY: summary, + RELEASE_TAG: 'v0.3.2', + }, + }) + return { status: result.status, output: readFileSync(output, 'utf8'), summary: readFileSync(summary, 'utf8') } + } finally { + rmSync(dir, { recursive: true, force: true }) + } +} + +test('a release that already exists ends the run before anything is built', () => { + const run = runGuard(0) + assert.equal(run.status, 0, 'the guard is a clean exit, not a failure') + assert.match(run.output, /^published=true$/m, 'the run is marked as already published') + assert.match(run.summary, /already|exists/i, 'the summary says why the run stopped') +}) + +test('a release that does not exist still publishes', () => { + const run = runGuard(1) + assert.equal(run.status, 0, 'a missing release is not an error') + assert.match(run.output, /^published=false$/m, 'the run is marked as not published') +}) + +test('the guard runs before the build, and every write after it is gated on the answer', () => { + const blocks = stepBlocks(release) + const guardIndex = blocks.findIndex((block) => stepName(block) === GUARD) + const buildIndex = blocks.findIndex((block) => stepName(block).includes('Build the image')) + assert.notEqual(guardIndex, -1, 'the guard step exists') + assert.notEqual(buildIndex, -1, 'the build step exists') + assert.ok(guardIndex < buildIndex, 'the guard precedes the build, so a published release never reaches it') + + // Every step after the guard either writes the image, the notes or the release, + // or derives what they use: all of them carry the gate. The assertion is the + // gate itself, which is what keeps a second dispatch from republishing. + const after = blocks.slice(guardIndex + 1) + assert.ok(after.length >= 5, 'the guard sits above the publishing steps') + for (const block of after) { + assert.match(block, new RegExp(`if: \\$\\{\\{ ${GATE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} \\}\\}`), `step "${stepName(block)}" is gated on the guard`) + } +}) + +test('the guard reads the release state, it does not trust a local file', () => { + const body = runBody(guardBlock()) + assert.match(body, /gh release view "\$\{?RELEASE_TAG\}?"/, 'the release state comes from the API for this tag') + assert.match(body, /GITHUB_OUTPUT/, 'the answer is an output the publishing steps read') + assert.equal(body.includes('${{'), false, 'no expression is spliced into the shell body') +}) diff --git a/test/releaseTagPlan.test.ts b/test/releaseTagPlan.test.ts new file mode 100644 index 00000000..a04cf239 --- /dev/null +++ b/test/releaseTagPlan.test.ts @@ -0,0 +1,160 @@ +import test from 'node:test' +import assert from 'node:assert/strict' + +import { plan, resolveTarget } from '../scripts/lib/release-tag.mjs' + +// #866: a release has two independent write moments, the tag and the publish run +// dispatched at it. The tag job answered `skip` as soon as the tag existed, so a +// dispatch that failed after the tag was created could never be retried — the +// tag was there, every later run skipped, and no GitHub Release, image or SBOM +// was ever produced. These tests pin the decision table: create when the tag is +// missing, publish when the tag exists without its release, and nothing when +// both exist. + +const SHA = 'a'.repeat(40) +const OTHER = 'b'.repeat(40) + +function releasePr(overrides: Record = {}) { + return { + number: 41, + title: 'release: v0.3.2', + merged_at: '2026-11-15T00:00:00Z', + merge_commit_sha: SHA, + head: { ref: 'release/v0.3.2' }, + ...overrides, + } +} + +function decide(overrides: Record = {}) { + return plan({ + pulls: [releasePr()], + tags: [], + release: null, + packageVersion: '0.3.2', + sha: SHA, + ...overrides, + }) +} + +test('a missing tag is created on the squash commit of the merged release pull request', () => { + const result = decide() + assert.equal(result.action, 'create') + assert.equal(result.tag, 'v0.3.2') + assert.equal(result.sha, SHA) + assert.match(result.reason, /squash commit/) +}) + +test('a tag that exists without its GitHub Release dispatches the publish run', () => { + const result = decide({ tags: ['v0.3.2'] }) + assert.equal(result.action, 'publish', 'the half-made release is finished, not skipped') + assert.equal(result.tag, 'v0.3.2') + assert.equal(result.sha, SHA) + assert.match(result.reason, /GitHub Release/) + assert.equal(/create/.test(result.action), false, 'publish never writes a second tag') +}) + +test('a tag that already has its release is a no-op, so a second run cannot publish twice', () => { + const result = decide({ tags: ['v0.3.2'], release: { tag_name: 'v0.3.2', draft: false } }) + assert.equal(result.action, 'skip') + assert.match(result.reason, /both exist/) +}) + +test('the identity check gates the publish path, so an ordinary push cannot re-dispatch a release', () => { + // A push that is not the release merge — here the squash sha differs — must not + // act on a tag that happens to exist, even though its package.json version is + // the released one. + const result = plan({ + pulls: [releasePr({ merge_commit_sha: OTHER })], + tags: ['v0.3.2'], + release: null, + packageVersion: '0.3.2', + sha: SHA, + }) + assert.equal(result.action, 'skip') + assert.match(result.reason, /not the squash commit/) +}) + +test('a tag ref in its full refs/tags form still counts as the existing tag', () => { + const result = decide({ tags: ['refs/tags/v0.3.2'] }) + assert.equal(result.action, 'publish') +}) + +test('the ambiguous shapes are refused instead of guessed', () => { + assert.equal(decide({ sha: 'a'.repeat(7) }).action, 'skip', 'a short sha is never resolved') + assert.equal(decide({ packageVersion: '' }).action, 'skip', 'no version is no tag name') + assert.equal(decide({ pulls: null }).action, 'skip', 'no pull request list is no identity') + assert.equal(decide({ pulls: [releasePr({ merged_at: null })] }).action, 'skip', 'an unmerged pull request is not a release') + assert.equal(decide({ pulls: [releasePr({ head: { ref: 'feature/x' } })] }).action, 'skip', 'a branch that is not release/v is not the release') + assert.equal(decide({ pulls: [releasePr(), releasePr({ number: 42 })] }).action, 'skip', 'two claimants are not resolved by picking one') +}) + +test('the publish path needs the tag to exist, and the create path needs it to be absent', () => { + for (const tags of [[], ['v0.3.1'], ['refs/tags/v0.3.1']]) { + assert.equal(decide({ tags }).action, 'create', `no v0.3.2 in ${JSON.stringify(tags)} means create`) + } + assert.equal(decide({ tags: ['v0.3.2'] }).action, 'publish') + assert.equal(decide({ tags: ['v0.3.2'], release: { tag_name: 'v0.3.2' } }).action, 'skip') +}) + +// #866, the scheduled half: on `schedule` the event's commit is `main`'s tip, +// and the identity check in `plan()` requires the release pull request's squash +// commit. Once any merge lands after the release merge, those are different +// commits, so a scheduled run could never repair the release it names — the +// nightly answered `skip` forever. `resolveTarget` names the commit the tag job +// is allowed to act on: the event's own commit on a push, the merged release +// pull request's merge commit on a schedule. +test('a push keeps the event commit, and a schedule resolves the release merge', () => { + const TIP = 'c'.repeat(40) + const MERGE = 'd'.repeat(40) + const releasePrs = [{ number: 88, title: 'release: v0.3.2', mergeCommit: { oid: MERGE }, headRefName: 'release/v0.3.2' }] + + const push = resolveTarget({ eventName: 'push', sha: TIP, version: '0.3.2', releasePrs }) + assert.deepEqual({ sha: push.sha, source: push.source }, { sha: TIP, source: 'event' }, 'a push acts on the commit that was pushed') + + const schedule = resolveTarget({ eventName: 'schedule', sha: TIP, version: '0.3.2', releasePrs }) + assert.equal(schedule.sha, MERGE, 'the scheduled run acts on the release merge, not on the tip main has moved to') + assert.equal(schedule.source, 'release-merge') + assert.match(schedule.reason, /#88/, 'the reason names the pull request it resolved') + + // Main moved on by one commit, the tag exists, the release does not: this is + // exactly the half-made release the scheduled slot is meant to finish, and the + // resolved target is what lets `plan()` reach it. + const planned = plan({ + pulls: [releasePr({ merge_commit_sha: MERGE })], + tags: ['v0.3.2'], + release: null, + packageVersion: '0.3.2', + sha: schedule.sha, + }) + assert.equal(planned.action, 'publish', 'main has moved on, and the scheduled run still finds that release pull request\'s merge sha') +}) + +test('a schedule that cannot name exactly one release pull request keeps the tip, so the plan refuses it', () => { + const TIP = 'c'.repeat(40) + const MERGE = 'd'.repeat(40) + const cases: Array<[string, unknown]> = [ + ['no list', null], + ['empty list', []], + ['another version', [{ title: 'release: v0.3.1', mergeCommit: { oid: MERGE } }]], + ['two claimants', [ + { title: 'release: v0.3.2', mergeCommit: { oid: MERGE } }, + { title: 'release: v0.3.2', mergeCommit: { oid: 'e'.repeat(40) } }, + ]], + ['no merge commit', [{ title: 'release: v0.3.2', mergeCommit: {} }]], + ['a short merge commit', [{ title: 'release: v0.3.2', mergeCommit: { oid: 'abcdef' } }]], + ] + for (const [label, releasePrs] of cases) { + const target = resolveTarget({ eventName: 'schedule', sha: TIP, version: '0.3.2', releasePrs: releasePrs as never }) + assert.equal(target.sha, TIP, `${label}: an unresolvable target stays the tip`) + assert.equal(target.source, 'event', label) + } + assert.equal(resolveTarget({ eventName: 'schedule', sha: TIP, version: '', releasePrs: [] }).sha, TIP, 'no version is no release to resolve') +}) + +test('the fix does not loosen the identity check: a moved-on tip is still refused', () => { + const TIP = 'c'.repeat(40) + const MERGE = 'd'.repeat(40) + const planned = plan({ pulls: [releasePr({ merge_commit_sha: MERGE })], tags: ['v0.3.2'], release: null, packageVersion: '0.3.2', sha: TIP }) + assert.equal(planned.action, 'skip', 'the tip of a main that moved on is still not the release merge') + assert.match(String(planned.reason), /not the squash commit/) +})