Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 67 additions & 12 deletions .github/workflows/daily-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -557,37 +561,83 @@ 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<version>` 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"
const TMP = process.env.RUNNER_TEMP ?? "/tmp"
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,
})
Expand All @@ -614,14 +664,19 @@ 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 }}
run: |
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"
28 changes: 28 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand All @@ -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 }}
Expand All @@ -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 }}
Expand All @@ -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 }}
Expand All @@ -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 }}
Expand All @@ -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 }}
Expand Down
1 change: 1 addition & 0 deletions changelog.d/866-finish-half-made-release.fixed.md
Original file line number Diff line number Diff line change
@@ -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.
45 changes: 45 additions & 0 deletions docs/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<version>` pull request from `release/v<version>`,
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<version>` 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
Expand Down
35 changes: 34 additions & 1 deletion scripts/lib/release-tag.d.mts
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,51 @@ 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
}

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
Loading
Loading