From f38575ca321a6d8a161057eae1c9681f39e1706a Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Sat, 7 Nov 2026 14:05:02 -0500 Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20release:=20make=20v6=20an=20off?= =?UTF-8?q?icial=20release=20line=20(v6.x.y=20tags)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- .github/release-lines.yml | 136 ++++++----- .github/scripts/integration-governance.cjs | 2 +- .github/workflows/dco-post-merge.yml | 3 +- .github/workflows/dco-push-delta.yml | 1 + .github/workflows/docs-link-check.yml | 2 + .github/workflows/podman-arm64-lane.yml | 2 + .github/workflows/podman-contract.yml | 2 + .github/workflows/podman-rootful-lane.yml | 2 + .github/workflows/podman-rootless-lane.yml | 2 + .github/workflows/promote-stable.yml | 21 +- .github/workflows/quadlet-gate.yml | 2 + .github/workflows/scorecard.yml | 2 +- .github/workflows/suid-contract.yml | 2 + .github/workflows/tagged-release.yml | 256 +++++++++++++++------ changelog.d/added-v6-release-line.md | 1 + src/docs/release-channels.md | 2 +- src/docs/release-line-guard.md | 38 ++- src/docs/releases.md | 74 +++--- src/scripts/check-release-lines.sh | 41 +++- src/scripts/test-release-lines-guard.sh | 34 +++ 20 files changed, 446 insertions(+), 179 deletions(-) create mode 100644 changelog.d/added-v6-release-line.md diff --git a/.github/release-lines.yml b/.github/release-lines.yml index ff6ec35ba6..c026f34539 100644 --- a/.github/release-lines.yml +++ b/.github/release-lines.yml @@ -25,10 +25,21 @@ # CUTTING A NEW RELEASE LINE: add the branch name to `release_lines` below AND # to every workflow listed under `pinned` AND to every list under `env_lists`. # The guard fails until all three are done — that is the whole point, so do not -# "fix" it by only editing one side. +# "fix" it by only editing one side. `release_lines` is ALSO the run-time +# allow-list tagged-release.yml and promote-stable.yml check before serving +# the branch they were started from (#9154): adding a line here is what lets it +# mint vN.x.y tags and promote `stable`. The rest of the cut (docker.yml +# channel rows, default branch, docs) is the checklist in +# src/docs/release-line-guard.md. -# The release lines CI is expected to cover. -release_lines: [v4, v5] +# The release lines CI is expected to cover. v6 was cut as a release line on +# 2026-11-07: it mints `v6.x.y` tags, GitHub Releases and SBOMs through +# tagged-release.yml like v5 does. Channel ownership did NOT move with it — +# v5 still publishes `candidate` + `:latest` and owns `stable` (promoted from +# the default branch by promote-stable.yml); v6 publishes `edge` + `v6-latest` +# (its own docker.yml rows). See src/docs/release-line-guard.md, "Cutting a +# new release line", and src/docs/releases.md. +release_lines: [v4, v5, v6] # Workflows whose branch filters are pinned to the release lines. # @@ -47,45 +58,45 @@ pinned: # sunset, and a PR targeting v2 runs the v2 merge-ref's workflows anyway, # where this file does not exist. Same excluded-not-backfilled reasoning as # docs-link-check.yml below. - # v6 is carried as an EXTRA on the workflows below rather than added to - # `release_lines`: it is a development line for the #7563 epic, not a - # supported release line with a GA bar. What it DOES need is the same PR - # gating as v4, because feature PRs target it directly (spine, mention - # triggers); without these extras a v6-base PR runs no Go build, test, or - # security lane at all. It is ALSO published — `v6-latest` and, once its own - # docker.yml rows say so, the `edge` channel (#7721 Phase 1) — which is the - # `env_lists` extra below, not a `release_lines` entry: publishing a line's - # image is a narrower commitment than covering it with every pinned lane. - changelog-fragment-guard.yml: [v5, v6] + # v6 used to be carried as an EXTRA on the PR-gating workflows below while + # it was the #7563 development line; since its cut (2026-11-07) it is a + # `release_lines` entry, so the extras are gone and every pinned lane that + # does not write down a `-v6` exclusion covers it. + changelog-fragment-guard.yml: [] # Static analysis and vulnerability scanning for the Go module. Pinned to the # release lines and nothing else: a feature branch gets the same gate through # `pull_request`, and running it on every pushed branch would burn runner # minutes re-scanning code that has not reached a release line. # Added with the docs link checker (#5278), after the v2 line was sunset - # (#5030-era). It gates src/docs/ links on v4 only; v2 is excluded rather - # than back-filled, because the workflow never ran there and adding it - # would gate a line no longer taking doc changes. + # (#5030-era). It gates src/docs/ links on every release line (#9476): v6 + # takes doc changes through feature PRs like the other lines, and without + # it a v6-base PR's broken doc links and stale code citations landed + # ungated. v2 was never back-filled: the workflow never ran there and the + # line is retired. docs-link-check.yml: [] - # Post-merge DCO monitor for protected branch history. It intentionally - # watches v4 and v5 only: v4 is the source line whose Tide squash commits - # triggered #6312, and v5 is the sync target that inherits those commits. - dco-post-merge.yml: [v5] - # Push-scoped delta DCO gate (#6756). Same v4/v5 coverage and reasoning as - # dco-post-merge.yml above: v4 is the line whose pushes it audits, v5 the - # sync target inheriting them; v2 is sunset and takes no pushes. - dco-push-delta.yml: [v5] - # FOSSA license scanning runs on the active CNCF onboarding line only; - # v4 is feature-frozen and not being imported as the initial Hive Commons - # CNCF FOSSA project. - fossa.yml: [-v4] - # GitHub Actions Workflow triage compiles only on the active v5 line; older - # release lines do not carry the gh-aw automation surface. - gh-aw-compile.yml: [-v4] + # Post-merge DCO monitor for protected branch history. It watches every + # release line: v4 is the source line whose Tide squash commits triggered + # #6312, and v5 and v6 are the sync targets that inherit those commits. + dco-post-merge.yml: [] + # Push-scoped delta DCO gate (#6756). Same coverage and reasoning as + # dco-post-merge.yml above: v4 is the line whose pushes it audits, v5 and + # v6 the sync targets inheriting them; v2 is sunset and takes no pushes. + dco-push-delta.yml: [] + # FOSSA license scanning runs on the CNCF onboarding line only: the Hive + # Commons FOSSA project is imported from ONE branch, v5. v4 is + # feature-frozen; v6 inherits v5's dependency set through the top-ups and + # is not a second FOSSA project. + fossa.yml: [-v4, -v6] + # GitHub Actions Workflow triage compiles only on the default v5 line, where + # the gh-aw agentic workflows are registered; v4 does not carry the gh-aw + # automation surface and v6 only mirrors v5's compiled lock files. + gh-aw-compile.yml: [-v4, -v6] # Self-test for the hive-action-smoke dispatch workflow (#12964). Its push # trigger names v5 only: the smoke workflow is registered on v5 and does not # exist on the feature-frozen v4 line, so there is nothing there to test. - hive-action-smoke-tests.yml: [-v4] - go-security-analysis.yml: [v5, v6] + # v6 carries its own action unit gate (hive-action-tests.yml, v6 only). + hive-action-smoke-tests.yml: [-v4, -v6] + go-security-analysis.yml: [] podman-arm64-lane.yml: [] podman-contract.yml: [] podman-rootful-lane.yml: [] @@ -118,46 +129,48 @@ pinned: # They react to PRs into, and pushes to, the lines that take feature PRs: # v5 (stable + candidate) and v6 (edge). v4 is feature-frozen and takes no # new PRs, so there is nothing there to order or refresh. - pr-overlap.yml: [v6, -v4] - pr-auto-update.yml: [v6, -v4] - pr-auto-update-test.yml: [v6, -v4] + pr-overlap.yml: [-v4] + pr-auto-update.yml: [-v4] + pr-auto-update-test.yml: [-v4] # Native queue admission is available on the active feature lines only. # This is CI coverage, not an opt-in or a queue rule for either branch. - native-queue-policy.yml: [v6, -v4] - testutil-guard.yml: [v5, v6] - v2-ci.yml: [v5, v6] - v2-tests.yml: [v5, v6] + native-queue-policy.yml: [-v4] + testutil-guard.yml: [] + v2-ci.yml: [] + v2-tests.yml: [] # Automated v4 -> v5 forward-merge cadence (#7297). Its only branch filter is # the `workflow_run` trigger, which names the line whose RELEASES it reacts # to — v4, the source of every top-up. v2 is sunset and cuts no releases to # carry forward, and v5 is the merge TARGET rather than a trigger, so it is - # not a branch this workflow watches (on v5, where v5 is itself a release - # line, it must be excluded explicitly for the same reason). - v5-topup.yml: [-v5] + # not a branch this workflow watches (v5 and v6 are release lines too, so + # they must be excluded explicitly for the same reason — v6 reaches v4's + # releases through v5). + v5-topup.yml: [-v5, -v6] # Post-freeze intake gate for v4 (#7693, runbook §2). It watches PRs into # the ONE line the accepted freeze policy (#6346) applies to; v2 is sunset # and takes no PRs, and v5/v6 are exactly where non-critical work is sent. - v4-freeze-gate.yml: [-v5] + v4-freeze-gate.yml: [-v5, -v6] # Automated v5 -> v6 forward-merge cadence (#7563, Track 7). Its only branch # filter is the `push` trigger naming the line whose MOVEMENT it reacts to — - # v5, the source of every v6 top-up. v2 and v4 are excluded for the same - # reason as v5-topup.yml's exclusions: they are not the branch this workflow - # watches (v4 reaches v6 through v5), and v6 is the merge TARGET, not a - # trigger. - v6-topup.yml: [v5, -v4] + # v5, the source of every v6 top-up. v4 is excluded for the same reason as + # v5-topup.yml's exclusions: it is not the branch this workflow watches (v4 + # reaches v6 through v5), and v6 is the merge TARGET, not a trigger. + v6-topup.yml: [-v4, -v6] # Publishes src/crux to hivecommons/crux (#14138). It watches the ONE line # the published module is cut from — v5, where the nested module lives and # where `crux/vX.Y.Z` tags are made. v4 is feature-frozen and has no - # src/crux; publishing from two lines would race on hivecommons/crux main. - crux-sync.yml: [-v4] + # src/crux; v6 carries a copy through the top-ups but publishing from two + # lines would race on hivecommons/crux main. + crux-sync.yml: [-v4, -v6] # Nightly + path-filtered Forgejo smoke (#14116). Its push/pull_request - # filters name v5 only: the forge.Merger it exercises lives on v5, and v4 is - # feature-frozen. - forgejo-smoke.yml: [-v4] + # filters name v5 only: it exercises the forge.Merger against a live Forgejo + # and one line's coverage is enough for a shared package — v6 inherits the + # package through the top-ups, and v4 is feature-frozen. + forgejo-smoke.yml: [-v4, -v6] # Publishes the headless Twitch streamer image (#15594) from v5 only: the - # dashboard's `?kiosk=1` mode it depends on lives on v5 and v4 is - # feature-frozen. The image is operator tooling, not a hive release channel. - stream-image.yml: [-v4] + # image is operator tooling, not a hive release channel, so it follows the + # default branch rather than every release line; v4 is feature-frozen. + stream-image.yml: [-v4, -v6] # Workflows that deliberately do NOT pin to the release lines. Each must keep a # wildcard branch filter; if one is ever narrowed to a fixed list, the guard @@ -185,11 +198,10 @@ env_lists: # docker.yml's gate job: only long-lived branches push to GHCR. `mk` and `dd` # are standing experimental branches — not release lines, but branches a hive # can be assigned to, so they legitimately publish a `-latest` tag. - # `v6` is the #7563 development line, published so the `edge` channel can be - # re-based on it (#7721 Phase 1): `v6-latest` must exist before v6's own - # docker.yml publish rows can point `edge` at it. Every release branch that - # carries this list names v6 here, so the guard agrees across lines. - docker.yml LONG_LIVED: [mk, dd, v6] + # `v6` used to be an extra here while it was the #7563 development line + # (published so the `edge` channel could be re-based on it, #7721 Phase 1); + # since its cut it is a release line and covered without an extra. + docker.yml LONG_LIVED: [mk, dd] # MAINTAINER DECISION (#4405, answered by #8061 on 2026-09-21): `v2` is retired. # It was removed from `release_lines`, from every workflow that named it, and diff --git a/.github/scripts/integration-governance.cjs b/.github/scripts/integration-governance.cjs index f117381e0d..ad2ede5bcb 100644 --- a/.github/scripts/integration-governance.cjs +++ b/.github/scripts/integration-governance.cjs @@ -9,7 +9,7 @@ const MAX_COMMITS = 1000; const MAX_AUTHOR_BATCH = 50; // This literal is inside the enrolled .github closure. A caller-supplied // preparedBy.sourceSHA must never choose a new executable verifier tree. -const TRUSTED_SCRIPTS_TREE = 'af7a0249a3df8e6197ff49031d4cb6c4e00581c6'; +const TRUSTED_SCRIPTS_TREE = 'e7c942c022e901723f7b629550e1dc9309858ffa'; const SOURCE = 'https://github.com/kubernetes-sigs/kubebuilder-release-tools/tree/012269a88fa4c034a0acf1ba84c26b195c0dbab4'; const sha = value => crypto.createHash('sha256').update(value).digest('hex'); const git = (args, cwd = process.cwd()) => diff --git a/.github/workflows/dco-post-merge.yml b/.github/workflows/dco-post-merge.yml index c681aab0ec..8f61fb8bf0 100644 --- a/.github/workflows/dco-post-merge.yml +++ b/.github/workflows/dco-post-merge.yml @@ -5,6 +5,7 @@ on: branches: - v4 - v5 + - v6 # The checker itself is in scope, not just the history it checks. Until this # filter was added, src/scripts/test-check-dco-trailers.sh existed but no # workflow ever ran it — a change to the checker (or to the waiver logic that @@ -368,7 +369,7 @@ jobs: strategy: fail-fast: false matrix: - branch: [v4, v5] + branch: [v4, v5, v6] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 if: github.event_name != 'push' || github.ref == format('refs/heads/{0}', matrix.branch) diff --git a/.github/workflows/dco-push-delta.yml b/.github/workflows/dco-push-delta.yml index 670d0b7609..16a5189ad2 100644 --- a/.github/workflows/dco-push-delta.yml +++ b/.github/workflows/dco-push-delta.yml @@ -32,6 +32,7 @@ on: branches: - v4 - v5 + - v6 permissions: contents: read diff --git a/.github/workflows/docs-link-check.yml b/.github/workflows/docs-link-check.yml index 8dad235088..d119c8c47b 100644 --- a/.github/workflows/docs-link-check.yml +++ b/.github/workflows/docs-link-check.yml @@ -38,6 +38,7 @@ on: branches: - v4 - v5 + - v6 paths: - '*.md' - 'src/docs/**' @@ -62,6 +63,7 @@ on: branches: - v4 - v5 + - v6 paths: - '*.md' - 'src/docs/**' diff --git a/.github/workflows/podman-arm64-lane.yml b/.github/workflows/podman-arm64-lane.yml index 33202a3676..31ba339589 100644 --- a/.github/workflows/podman-arm64-lane.yml +++ b/.github/workflows/podman-arm64-lane.yml @@ -92,6 +92,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/podman-arm64-lane.yml' @@ -100,6 +101,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: inputs: image: diff --git a/.github/workflows/podman-contract.yml b/.github/workflows/podman-contract.yml index 649b404a6a..4fa12c63d7 100644 --- a/.github/workflows/podman-contract.yml +++ b/.github/workflows/podman-contract.yml @@ -23,6 +23,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'Justfile' - 'src/scripts/check-podman-contract.sh' @@ -32,6 +33,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'Justfile' - 'src/scripts/check-podman-contract.sh' diff --git a/.github/workflows/podman-rootful-lane.yml b/.github/workflows/podman-rootful-lane.yml index 073366d802..ddd8605d3f 100644 --- a/.github/workflows/podman-rootful-lane.yml +++ b/.github/workflows/podman-rootful-lane.yml @@ -70,6 +70,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/podman-rootful-lane.yml' @@ -78,6 +79,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: inputs: somark: diff --git a/.github/workflows/podman-rootless-lane.yml b/.github/workflows/podman-rootless-lane.yml index d00c51017b..bfa77f7971 100644 --- a/.github/workflows/podman-rootless-lane.yml +++ b/.github/workflows/podman-rootless-lane.yml @@ -51,6 +51,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/podman-rootless-lane.yml' @@ -59,6 +60,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: inputs: bypass: diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.yml index 1e4815957b..4dfd3f8a57 100644 --- a/.github/workflows/promote-stable.yml +++ b/.github/workflows/promote-stable.yml @@ -43,12 +43,19 @@ permissions: issues: write packages: write +# RELEASE LINE (#9154): `stable` is promoted from the candidate published by +# the branch this run was started from — the default branch for `schedule`, +# the chosen ref for `workflow_dispatch` — never a literal. The first step +# refuses unless that branch is under `release_lines` in +# .github/release-lines.yml, so a dispatch from a development line can no +# longer promote another line's candidate, and cutting a new line needs no +# edit here. Checklist: src/docs/release-line-guard.md. concurrency: - group: stable-promotion-v5 + group: stable-promotion-${{ github.ref_name }} cancel-in-progress: false env: - RELEASE_BRANCH: v5 + RELEASE_BRANCH: ${{ github.ref_name }} SOAK_HOURS: ${{ inputs.soak-hours || '24' }} DRY_RUN: ${{ inputs.dry-run || 'false' }} IMAGE_NAMES: hive hive-contributor hive-hub @@ -118,8 +125,14 @@ jobs: steps: - name: Checkout promotion scripts uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: v5 + + - name: Require the triggering branch to be a declared release line + run: | + set -euo pipefail + if ! src/scripts/check-release-lines.sh --is-release-line "$RELEASE_BRANCH"; then + echo "::error::Promote Stable was started from '${RELEASE_BRANCH}', which is not under release_lines in .github/release-lines.yml, so it has no candidate to promote. Dispatch it from a release line, or cut this branch as one first (src/docs/release-line-guard.md)." >&2 + exit 1 + fi - name: Set up Docker Buildx uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 diff --git a/.github/workflows/quadlet-gate.yml b/.github/workflows/quadlet-gate.yml index 27ef5890cb..58f8817c6a 100644 --- a/.github/workflows/quadlet-gate.yml +++ b/.github/workflows/quadlet-gate.yml @@ -62,6 +62,7 @@ on: branches: - v4 - v5 + - v6 pull_request: paths: - '.github/workflows/quadlet-gate.yml' @@ -70,6 +71,7 @@ on: branches: - v4 - v5 + - v6 workflow_dispatch: permissions: diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 9612d2a745..acdf52677f 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -4,7 +4,7 @@ on: schedule: - cron: '0 6 * * 1' push: - branches: [ "main", "v4", "v5" ] + branches: [ "main", "v4", "v5", "v6" ] workflow_dispatch: permissions: diff --git a/.github/workflows/suid-contract.yml b/.github/workflows/suid-contract.yml index a13410b915..120e34eb6c 100644 --- a/.github/workflows/suid-contract.yml +++ b/.github/workflows/suid-contract.yml @@ -22,6 +22,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'src/Dockerfile' - 'src/deploy/entrypoint.sh' @@ -39,6 +40,7 @@ on: branches: - v4 - v5 + - v6 paths: - 'src/Dockerfile' - 'src/deploy/entrypoint.sh' diff --git a/.github/workflows/tagged-release.yml b/.github/workflows/tagged-release.yml index 9ccb2800f9..872901f0fe 100644 --- a/.github/workflows/tagged-release.yml +++ b/.github/workflows/tagged-release.yml @@ -7,12 +7,12 @@ name: Tagged Release # the short version. # # TRIGGER: `workflow_run` on "Build and Push Docker Image" (docker.yml) -# completing successfully on branch v5. NOT a tag push — there is no tag until -# THIS workflow creates one. Chaining off docker.yml rather than a parallel -# `push: branches: [v5]` trigger means this workflow only ever runs after the -# continuous-delivery images for that exact commit are already published, -# which is also the digest this workflow retags — it can never race ahead of -# or duplicate that build. +# completing successfully on the release line this run serves. NOT a tag push +# — there is no tag until THIS workflow creates one. Chaining off docker.yml +# rather than a parallel `push:` trigger means this workflow only ever runs +# after the continuous-delivery images for that exact commit are already +# published, which is also the digest this workflow retags — it can never +# race ahead of or duplicate that build. # # DECISION: src/scripts/derive-release-version.sh reads CHANGELOG.md's # `## Unreleased` section (already the human-curated, PR-time judgment call @@ -161,10 +161,34 @@ on: - cron: "37 * * * *" workflow_dispatch: +# RELEASE LINE (#9154): the line is the branch this run was started from — +# the default branch for `workflow_run`/`schedule`, the chosen ref for +# `workflow_dispatch` — never a literal. The `decide` job refuses unless that +# branch is under `release_lines` in .github/release-lines.yml, so the same +# file is correct on every line, a dispatch from a development line (v6 before +# its cut) can no longer release another line's tip, and cutting a new line +# needs no edit here. Checklist: src/docs/release-line-guard.md. +# +# NON-DEFAULT RELEASE LINES: GitHub delivers `workflow_run` and `schedule` +# events ONLY to the default branch's copy of this file, so a docker.yml run +# on another release line (v6 after its cut) never reaches that line's own +# copy by itself. The `relay` job below closes that gap: when the default +# copy sees a successful push/dispatch build of ANOTHER declared release line, +# it dispatches this workflow on that line (`--ref `), and the dispatched +# run takes the backstop path — resolve the line's tip, require its images to +# be published, derive, release — under that line's own `concurrency` group. +# The relay is event-driven only: the hourly schedule stays a default-branch +# backstop, and a non-default line whose build was cancelled is picked up by +# its next completed build or by a manual `gh workflow run tagged-release.yml +# --ref `. The relay reads release_lines from ITS OWN checkout (the +# default branch), never from the line it is relaying to. concurrency: - group: tagged-release-v5 + group: tagged-release-${{ github.ref_name }} cancel-in-progress: false +env: + RELEASE_LINE: ${{ github.ref_name }} + permissions: contents: write packages: write @@ -184,18 +208,73 @@ permissions: issues: write jobs: + # Relay a non-default release line's completed build to that line's own copy + # of this workflow (see NON-DEFAULT RELEASE LINES in the header). Same + # event/conclusion filter as `decide`, with the branch test inverted; the + # release-line test itself needs the manifest, so it happens in the step. + relay: + if: >- + github.event_name == 'workflow_run' && + github.event.workflow_run.conclusion == 'success' && + ( github.event.workflow_run.event == 'push' || github.event.workflow_run.event == 'workflow_dispatch' ) && + github.event.workflow_run.head_branch != github.ref_name + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + actions: write + steps: + - name: Checkout the release-line manifest from this workflow's ref + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + sparse-checkout: | + .github/release-lines.yml + src/scripts/check-release-lines.sh + sparse-checkout-cone-mode: false + + - name: Dispatch Tagged Release on the built release line + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + LINE: ${{ github.event.workflow_run.head_branch }} + BUILT_SHA: ${{ github.event.workflow_run.head_sha }} + run: | + set -euo pipefail + # head_branch is attacker-free here (push/workflow_dispatch builds + # are always this repository's own branches) but is still a free + # string; refuse anything that is not a plain vN before it reaches + # a --ref argument. + if ! [[ "$LINE" =~ ^v[0-9]+$ ]]; then + echo "docker.yml built '${LINE}', which is not a vN branch; nothing to relay." + exit 0 + fi + if ! src/scripts/check-release-lines.sh --is-release-line "$LINE"; then + echo "docker.yml built '${LINE}', which is not under release_lines in .github/release-lines.yml; nothing to relay." + exit 0 + fi + echo "docker.yml published ${BUILT_SHA} on release line ${LINE}; dispatching Tagged Release on ${LINE} so its own copy can consider it." + gh workflow run tagged-release.yml --repo "${{ github.repository }}" --ref "$LINE" + decide: - # workflow_run: only a successful docker.yml build for v5. Both push and - # workflow_dispatch builds count: post-release dispatches are harmless - # because Unreleased is already empty, and the backstop below may need to - # prime docker.yml manually when a busy branch's current tip has not yet - # published images. + # workflow_run: only a successful docker.yml build of a real push to, or + # a workflow_dispatch on, the release line. The event filter is what makes + # `head_branch` trustworthy: docker.yml also runs on `pull_request` with + # no branch filter, and a fork PR's `head_branch` is whatever the fork + # named its branch — `v5` included — so comparing the name alone would + # admit a fork's commit. Push and workflow_dispatch runs are always on one + # of this repository's own branches. Both count (#10863): post-release + # dispatches are harmless because Unreleased is already empty, and the + # backstop below may need to prime docker.yml manually when a busy line's + # current tip has not yet published images. (The scratch-branch gate + # dance's dispatch runs on release-gate/*, never on the line itself, so the + # head_branch check still keeps us off our own tail.) # schedule/workflow_dispatch: the #5318 backstop, which has no triggering - # run to qualify and instead resolves v5's current tip below. + # run to qualify and instead resolves the line's current tip below. if: >- github.event_name != 'workflow_run' || ( github.event.workflow_run.conclusion == 'success' && - github.event.workflow_run.head_branch == 'v5' ) + ( github.event.workflow_run.event == 'push' || github.event.workflow_run.event == 'workflow_dispatch' ) && + github.event.workflow_run.head_branch == github.ref_name ) runs-on: ubuntu-latest timeout-minutes: 10 outputs: @@ -205,7 +284,7 @@ jobs: sha: ${{ steps.target.outputs.sha }} steps: # workflow_run carries the exact commit docker.yml built. The backstop - # has no such commit, so it resolves v5's tip — whose images are already + # has no such commit, so it resolves the line's tip — whose images are already # published (its docker.yml run completed long before an hourly tick), # which is what keeps the retag honest. - name: Resolve the commit to consider releasing @@ -218,11 +297,42 @@ jobs: sha="${{ github.event.workflow_run.head_sha }}" echo "Triggered by docker.yml on ${sha}." else - sha="$(gh api "repos/${{ github.repository }}/branches/v5" --jq .commit.sha)" - echo "Backstop (${{ github.event_name }}): considering v5 tip ${sha}." + sha="$(gh api "repos/${{ github.repository }}/branches/${RELEASE_LINE}" --jq .commit.sha)" + echo "Backstop (${{ github.event_name }}): considering ${RELEASE_LINE} tip ${sha}." fi echo "sha=${sha}" >> "$GITHUB_OUTPUT" + # #9154: refuse any branch that is not a declared release line. Without + # this, a dispatch from a development line would derive and tag it as if + # it were one. A red run is right here: every automatic trigger resolves + # to the default branch, so only a manual dispatch from the wrong ref + # can reach the refusal. + # + # The guard and its manifest come from this workflow's own ref + # (github.sha: the default branch for workflow_run/schedule, the + # dispatched ref for workflow_dispatch — the same tree this workflow + # file was read from), never from the commit being considered, and run + # before that commit is checked out. A check read from the target tree + # would let whoever wrote that tree approve it. + - name: Checkout the release-line guard from this workflow's ref + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + path: .release-line-guard + persist-credentials: false + sparse-checkout: | + .github/release-lines.yml + src/scripts/check-release-lines.sh + sparse-checkout-cone-mode: false + + - name: Require the triggering branch to be a declared release line + working-directory: .release-line-guard + run: | + set -euo pipefail + if ! src/scripts/check-release-lines.sh --is-release-line "$RELEASE_LINE"; then + echo "::error::Tagged Release was started from '${RELEASE_LINE}', which is not under release_lines in .github/release-lines.yml, so it has no tag line to cut. Dispatch it from a release line, or cut this branch as one first (src/docs/release-line-guard.md)." >&2 + exit 1 + fi + - name: Checkout the commit docker.yml just built uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: @@ -246,16 +356,16 @@ jobs: run: | set -euo pipefail sha="${{ steps.target.outputs.sha }}" - # A `push` run is the normal case; a `workflow_dispatch` run on v5 - # is the post-release exact-SHA rebuild of a GITHUB_TOKEN merge commit - # (#6380). Both publish the / v5-latest / candidate tags, so - # both count as published for the backstop. + # A `push` run is the normal case; a `workflow_dispatch` run on the + # line is the post-release exact-SHA rebuild of a GITHUB_TOKEN merge + # commit (#6380). Both publish the / -latest / channel + # tags, so both count as published for the backstop. conclusion="$(gh api \ "repos/${{ github.repository }}/actions/workflows/docker.yml/runs?head_sha=${sha}&status=completed" \ - --jq '[.workflow_runs[] | select(.event == "push" or (.event == "workflow_dispatch" and .head_branch == "v5"))] | last | .conclusion // ""')" + --jq "[.workflow_runs[] | select(.event == \"push\" or (.event == \"workflow_dispatch\" and .head_branch == \"${RELEASE_LINE}\"))] | last | .conclusion // \"\"")" if [ "$conclusion" != "success" ]; then - echo "::warning::Backstop standing down: docker.yml has no successful completed publishing run for v5 tip ${sha} (found '${conclusion:-none}'), so there is no published digest to retag yet. Dispatching docker.yml for v5; if v5 is still at the published SHA when that run completes, its workflow_run will continue this release opportunity (#5318)." - gh workflow run docker.yml --ref v5 + echo "::warning::Backstop standing down: docker.yml has no successful completed publishing run for ${RELEASE_LINE} tip ${sha} (found '${conclusion:-none}'), so there is no published digest to retag yet. Dispatching docker.yml for ${RELEASE_LINE}; if ${RELEASE_LINE} is still at the published SHA when that run completes, its workflow_run will continue this release opportunity (#5318)." + gh workflow run docker.yml --ref "$RELEASE_LINE" echo "published=false" >> "$GITHUB_OUTPUT" exit 0 fi @@ -276,22 +386,20 @@ jobs: id: derive if: github.event_name == 'workflow_run' || steps.images.outputs.published == 'true' # The checkout above is a detached SHA, so the script cannot read the - # line from the branch name; name it explicitly. This workflow is - # pinned to v5 everywhere else (concurrency, --base, --ref), and the - # script refuses to run without it. - env: - RELEASE_LINE: v5 + # line from the branch name; it reads the workflow-level RELEASE_LINE + # instead (the same value as concurrency, --base, --ref), and refuses + # to run without it. run: src/scripts/derive-release-version.sh - # Cheap supersession check BEFORE the expensive release job (#5142): if v5 - # already moved past the commit this run was triggered for, every minute + # Cheap supersession check BEFORE the expensive release job (#5142): if the + # line already moved past the commit this run was triggered for, every minute # spent here is wasted — the final push can only ever be rejected # non-fast-forward — and worse, the `concurrency` group above serializes # release runs, so a doomed run delays the successor that CAN release. One # API call decides in seconds. # # #5318: this job used to claim the successor was GUARANTEED to exist ("the - # merge that advanced v5 triggered docker.yml, whose completion triggers + # merge that advanced the line triggered docker.yml, whose completion triggers # tagged-release.yml for that newer tip"). That guarantee does not hold — a # cancelled docker.yml run fires no workflow_run at all, and a successor # that does fire applies this same test and defers again. Deferring is still @@ -310,40 +418,40 @@ jobs: hold_sha: ${{ steps.tip.outputs.hold_sha }} held_prs: ${{ steps.tip.outputs.held_prs }} steps: - - name: Defer to the successor run if v5 already advanced + - name: Defer to the successor run if the release line already advanced id: tip env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | set -euo pipefail sha="${{ needs.decide.outputs.sha }}" - tip="$(gh api "repos/${{ github.repository }}/branches/v5" --jq .commit.sha)" + tip="$(gh api "repos/${{ github.repository }}/branches/${RELEASE_LINE}" --jq .commit.sha)" if [ "$tip" = "$sha" ]; then - echo "v5 is still at ${sha} — proceeding with the release." + echo "${RELEASE_LINE} is still at ${sha} — proceeding with the release." gh api --method POST "repos/${{ github.repository }}/statuses/${sha}" \ -f state=pending \ -f context=release-in-progress \ - -f description="Tagged Release is holding v5 merges for up to ${{ vars.RELEASE_MERGE_HOLD_SECONDS || '300' }}s" + -f description="Tagged Release is holding ${RELEASE_LINE} merges for up to ${{ vars.RELEASE_MERGE_HOLD_SECONDS || '300' }}s" gh label create "do-not-merge/hold" --color bfdadc --description "Temporarily blocks Tide/hive automerge" >/dev/null 2>&1 || true held_prs="" while IFS= read -r pr; do [ -n "$pr" ] || continue gh pr edit "$pr" --add-label "do-not-merge/hold" held_prs="${held_prs}${held_prs:+,}${pr}" - done < <(gh pr list --base v5 --state open --limit 200 --json number,labels --jq '.[] | select(([.labels[].name] | index("do-not-merge/hold")) | not) | .number') + done < <(gh pr list --base "$RELEASE_LINE" --state open --limit 200 --json number,labels --jq '.[] | select(([.labels[].name] | index("do-not-merge/hold")) | not) | .number') echo "Temporarily applied do-not-merge/hold to PRs: ${held_prs:-}." echo "proceed=true" >> "$GITHUB_OUTPUT" echo "hold_sha=${sha}" >> "$GITHUB_OUTPUT" echo "held_prs=${held_prs}" >> "$GITHUB_OUTPUT" else - echo "::warning::Release opportunity skipped for ${sha}: v5 is already at ${tip}. Deferring — this run's images were built from the older tree, so it must not tag. Unreleased is untouched, so nothing is dropped: either a successor run releases it, or the hourly backstop does. See the RACES note and the BACKSTOP note in this workflow's header (#5142/#5318)." - existing="$(gh api "repos/${{ github.repository }}/actions/workflows/docker.yml/runs?head_sha=${tip}&per_page=20" --jq '[.workflow_runs[] | select(.event == "push" or (.event == "workflow_dispatch" and .head_branch == "v5"))] | length')" + echo "::warning::Release opportunity skipped for ${sha}: ${RELEASE_LINE} is already at ${tip}. Deferring — this run's images were built from the older tree, so it must not tag. Unreleased is untouched, so nothing is dropped: either a successor run releases it, or the hourly backstop does. See the RACES note and the BACKSTOP note in this workflow's header (#5142/#5318)." + existing="$(gh api "repos/${{ github.repository }}/actions/workflows/docker.yml/runs?head_sha=${tip}&per_page=20" --jq "[.workflow_runs[] | select(.event == \"push\" or (.event == \"workflow_dispatch\" and .head_branch == \"${RELEASE_LINE}\"))] | length")" if [ "${existing:-0}" -eq 0 ]; then - gh workflow run docker.yml --ref v5 \ - && echo "Re-armed docker.yml for current v5 tip ${tip}." \ + gh workflow run docker.yml --ref "$RELEASE_LINE" \ + && echo "Re-armed docker.yml for current ${RELEASE_LINE} tip ${tip}." \ || echo "::warning::could not dispatch docker.yml for ${tip}; waiting for the next scheduled tick." else - echo "docker.yml already has ${existing} run(s) for current v5 tip ${tip}; not re-dispatching." + echo "docker.yml already has ${existing} run(s) for current ${RELEASE_LINE} tip ${tip}; not re-dispatching." fi echo "proceed=false" >> "$GITHUB_OUTPUT" fi @@ -537,7 +645,7 @@ jobs: # silently couple a version tag to it. - name: Confirm channel tags were not touched run: | - echo "This workflow only ever writes vX.Y.Z tags. stable/candidate/edge are owned exclusively by docker.yml's merge jobs on every push to v5, independent of whether a release was cut here." + echo "This workflow only ever writes vX.Y.Z tags. stable/candidate/edge are owned exclusively by docker.yml's merge jobs on every push to a release branch, independent of whether a release was cut here." # SBOM: a standalone release ARTIFACT, not an in-image attestation. # @@ -741,7 +849,7 @@ jobs: pending) ;; *) - echo "::error::gate concluded '${conclusion}' on ${commit_sha} — cannot push to v5." >&2 + echo "::error::gate concluded '${conclusion}' on ${commit_sha} — cannot push to ${RELEASE_LINE}." >&2 exit 1 ;; esac @@ -783,8 +891,8 @@ jobs: # pinned to ACTIONS_TOKEN below, like the docker.yml dispatch (#6380) # already was. Widening the PAT instead would hand a long-lived secret # readable by every workflow more power than this one step needs. - - name: Open and merge a PR from the scratch branch into v5 - id: push_v5 + - name: Open and merge a PR from the scratch branch into the release line + id: push_line env: GH_TOKEN: ${{ secrets.RELEASE_PR_TOKEN != '' && secrets.RELEASE_PR_TOKEN || secrets.GITHUB_TOKEN }} ACTIONS_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -894,43 +1002,43 @@ jobs: -f context=gate \ -f description="docker.yml gate verified for automated release" - echo "Trying direct v5 push first (#10863); falling back to the release PR path if branch protection rejects it..." - git fetch origin v5 - current_tip="$(git rev-parse origin/v5)" + echo "Trying direct ${RELEASE_LINE} push first (#10863); falling back to the release PR path if branch protection rejects it..." + git fetch origin "$RELEASE_LINE" + current_tip="$(git rev-parse "origin/${RELEASE_LINE}")" if [ "$current_tip" != "$SHA" ]; then - echo "::warning::Release opportunity skipped for ${SHA}: v5 advanced to ${current_tip} before the direct push. Nothing was pushed; Unreleased is untouched." + echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced to ${current_tip} before the direct push. Nothing was pushed; Unreleased is untouched." echo "pushed=false" >> "$GITHUB_OUTPUT" exit 0 fi - if direct_out="$(git push origin "HEAD:refs/heads/v5" 2>&1)"; then + if direct_out="$(git push origin "HEAD:refs/heads/${RELEASE_LINE}" 2>&1)"; then echo "$direct_out" release_sha="$commit_sha" merged=true - echo "Direct push landed release commit ${release_sha} on v5; dispatching docker.yml for the release commit (#6380)..." - GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref v5 \ + echo "Direct push landed release commit ${release_sha} on ${RELEASE_LINE}; dispatching docker.yml for the release commit (#6380)..." + GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref "$RELEASE_LINE" \ -f "release_sha=${release_sha}" \ -f "release_version=v${VERSION}" else echo "$direct_out" if grep -qiE 'non-fast-forward|fetch first|stale info' <<<"$direct_out"; then - echo "::warning::Release opportunity skipped for ${SHA}: v5 advanced during the direct push. Nothing was pushed; Unreleased is untouched." + echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced during the direct push. Nothing was pushed; Unreleased is untouched." echo "pushed=false" >> "$GITHUB_OUTPUT" exit 0 fi - git fetch origin v5 - current_tip="$(git rev-parse origin/v5)" + git fetch origin "$RELEASE_LINE" + current_tip="$(git rev-parse "origin/${RELEASE_LINE}")" if [ "$current_tip" != "$SHA" ]; then - echo "::warning::Release opportunity skipped for ${SHA}: v5 advanced to ${current_tip} while branch protection rejected the direct push. Nothing was pushed; Unreleased is untouched." + echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced to ${current_tip} while branch protection rejected the direct push. Nothing was pushed; Unreleased is untouched." echo "pushed=false" >> "$GITHUB_OUTPUT" exit 0 fi - echo "Direct push was rejected by branch protection (expected until the GitHub Actions app has a v5 bypass); falling back to the release PR path." + echo "Direct push was rejected by branch protection (expected until the GitHub Actions app has a ${RELEASE_LINE} bypass); falling back to the release PR path." fi if [ "$merged" != true ]; then - echo "Opening a PR from ${scratch} into v5..." + echo "Opening a PR from ${scratch} into ${RELEASE_LINE}..." if ! pr_url="$(gh pr create \ - --base v5 \ + --base "$RELEASE_LINE" \ --head "${scratch}" \ --title "release: v${VERSION}" \ --body "Automated release PR (#5222/#5356). Merges the release commit for v${VERSION}, carrying a successful gate check and mirrored status on ${commit_sha}." 2>&1)"; then @@ -1007,7 +1115,7 @@ jobs: repo="${GITHUB_REPOSITORY#*/}" # shellcheck disable=SC2016 # GraphQL variables are expanded by gh, not by the shell. if ! json="$(gh api graphql \ - -f owner="$owner" -f name="$repo" -F number="$pr" -f branch=v5 -f head="$head_sha" \ + -f owner="$owner" -f name="$repo" -F number="$pr" -f branch="$RELEASE_LINE" -f head="$head_sha" \ -f query=' query($owner:String!,$name:String!,$number:Int!,$branch:String!){ repository(owner:$owner,name:$name){ @@ -1127,9 +1235,9 @@ jobs: # #6380: the GITHUB_TOKEN-authenticated merge cannot emit a push # event to docker.yml. Dispatch immediately after the merge, # before tag work widens the ordering window; pass the API's exact - # SHA because the v5 ref can advance before the build starts. - echo "Dispatching docker.yml for merged release commit ${release_sha} on v5 (#6380)..." - GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref v5 \ + # SHA because the line's ref can advance before the build starts. + echo "Dispatching docker.yml for merged release commit ${release_sha} on ${RELEASE_LINE} (#6380)..." + GH_TOKEN="$ACTIONS_TOKEN" gh workflow run docker.yml --ref "$RELEASE_LINE" \ -f "release_sha=${release_sha}" \ -f "release_version=v${VERSION}" break @@ -1139,7 +1247,7 @@ jobs: # modified" (the sha= guard fired) or "Base branch was modified" — # both are the base-moved case, not something a retry fixes. if grep -qiE 'base branch was modified|head branch was modified|is out of date|HTTP 409' <<<"$out"; then - echo "::warning::Release opportunity skipped for ${SHA}: v5 advanced while this run was in flight — deferring (see the RACES note, #5142/#5222). Nothing was pushed; Unreleased is untouched, so either a successor run or the hourly backstop (#5318) releases it." + echo "::warning::Release opportunity skipped for ${SHA}: ${RELEASE_LINE} advanced while this run was in flight — deferring (see the RACES note, #5142/#5222). Nothing was pushed; Unreleased is untouched, so either a successor run or the hourly backstop (#5318) releases it." echo "pushed=false" >> "$GITHUB_OUTPUT" exit 0 fi @@ -1156,7 +1264,7 @@ jobs: sleep "$merge_poll_seconds" continue fi - echo "::error::PR #${pr_number} still not mergeable after ${merge_wait_seconds}s on ${commit_sha}. Required checks did not all report before the release merge deadline, or GitHub still rejected the SHA-keyed merge after they did; compare v5's REQUIRED contexts with the combined status for ${commit_sha}, including the mirrored gate status (#5356)." >&2 + echo "::error::PR #${pr_number} still not mergeable after ${merge_wait_seconds}s on ${commit_sha}. Required checks did not all report before the release merge deadline, or GitHub still rejected the SHA-keyed merge after they did; compare ${RELEASE_LINE}'s REQUIRED contexts with the combined status for ${commit_sha}, including the mirrored gate status (#5356)." >&2 exit 1 fi echo "::error::merging PR #${pr_number} failed for an unrecognized reason (see the API response above) — not retrying." >&2 @@ -1164,14 +1272,14 @@ jobs: done fi - # The merge landed a NEW commit on v5 (a merge commit, or the same + # The merge landed a NEW commit on the line (a merge commit, or the same # tree via fast-forward depending on PR mergeability). Fetch it so # the object exists locally, but tag the merge API's exact returned # SHA rather than re-resolving a branch that another PR can advance # between our merge and this fetch. - git fetch origin v5 - if ! git merge-base --is-ancestor "$release_sha" origin/v5; then - echo "::error::merge API returned ${release_sha}, but it is not contained in fetched origin/v5; refusing to tag or dispatch it." >&2 + git fetch origin "$RELEASE_LINE" + if ! git merge-base --is-ancestor "$release_sha" "origin/${RELEASE_LINE}"; then + echo "::error::merge API returned ${release_sha}, but it is not contained in fetched origin/${RELEASE_LINE}; refusing to tag or dispatch it." >&2 exit 1 fi git tag "v${VERSION}" "$release_sha" @@ -1202,7 +1310,7 @@ jobs: # auto-generated commit/PR summary so a Release is still created with a # useful body instead of leaving a tag-only ledger gap. - name: Create GitHub Release - if: steps.push_v5.outputs.pushed == 'true' + if: steps.push_line.outputs.pushed == 'true' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -1219,15 +1327,15 @@ jobs: echo echo "---" echo - echo "**SBOMs:** SPDX JSON, generated by Syft against the linux/amd64 image digest, attached below for \`hive\`, \`hive-contributor\`, and \`hive-hub\`. They cover linux/amd64 only — see [releases.md](https://github.com/${{ github.repository }}/blob/v5/src/docs/releases.md#software-bill-of-materials-sbom) for why linux/arm64 is not scanned separately." + echo "**SBOMs:** SPDX JSON, generated by Syft against the linux/amd64 image digest, attached below for \`hive\`, \`hive-contributor\`, and \`hive-hub\`. They cover linux/amd64 only — see [releases.md](https://github.com/${{ github.repository }}/blob/${RELEASE_LINE}/src/docs/releases.md#software-bill-of-materials-sbom) for why linux/arm64 is not scanned separately." echo - echo "**NOTICE:** third-party license attribution for the Go module dependencies compiled into these images, attached below. Does not cover base-image OS packages or the Node.js/tmux layers built from source — see [releases.md](https://github.com/${{ github.repository }}/blob/v5/src/docs/releases.md#third-party-notices) for the exact boundary." + echo "**NOTICE:** third-party license attribution for the Go module dependencies compiled into these images, attached below. Does not cover base-image OS packages or the Node.js/tmux layers built from source — see [releases.md](https://github.com/${{ github.repository }}/blob/${RELEASE_LINE}/src/docs/releases.md#third-party-notices) for the exact boundary." } >> "$notes_file" gh release create "v${VERSION}" \ --repo "${{ github.repository }}" \ --title "v${VERSION}" \ --notes-file "$notes_file" \ - --target v5 \ + --target "$RELEASE_LINE" \ "hive-v${VERSION}-sbom.spdx.json" \ "hive-contributor-v${VERSION}-sbom.spdx.json" \ "hive-hub-v${VERSION}-sbom.spdx.json" \ diff --git a/changelog.d/added-v6-release-line.md b/changelog.d/added-v6-release-line.md new file mode 100644 index 0000000000..4d2738f3d3 --- /dev/null +++ b/changelog.d/added-v6-release-line.md @@ -0,0 +1 @@ +- `v6` is now an official release line: `.github/release-lines.yml` lists `[v4, v5, v6]`, so `tagged-release.yml` mints `v6.x.y` tags (starting at `v6.0.0`), GitHub Releases, SBOMs and immutable image retags from the `v6` branch exactly as `v5` does; the default-branch copy of the workflow relays a completed `v6` build to `v6`'s own copy, since GitHub only delivers `workflow_run` to the default branch. Channel ownership is unchanged — `stable`/`candidate`/`:latest` follow `v5`, `edge`/`v6-latest` follow `v6`. diff --git a/src/docs/release-channels.md b/src/docs/release-channels.md index 212c6ef843..b65d08f543 100644 --- a/src/docs/release-channels.md +++ b/src/docs/release-channels.md @@ -10,7 +10,7 @@ Registry (**GHCR**). |---|---| | `stable` | Newest build promoted as generally safe to run. | | `candidate` | A v5 build awaiting the observation/waiting period (“soak”) before stable promotion. | -| `edge` | An active-development v6 build, with no soak period; not the newest v5 stable build. | +| `edge` | The newest v6 build, with no soak period; not the newest v5 stable build. Since 2026-11-07 v6 is a release line, so the same digest also carries an immutable `v6.x.y` tag once cut. | > **Promotion policy:** the channels diverge by release line and maturity. Every green merge to **`v5`** retags **`candidate`** (and `:latest`); **`stable`** advances later by digest through the scheduled/manual stable-promotion workflow after the [stable soak and promotion policy](stable-soak-policy.md) passes. Merges to **`v6`** retag **`edge`**, so `edge` is an active-development v6 build, not a synonym for `stable`. **`v4`** is a maintenance line: its builds publish only `v4-latest` and short-SHA tags, no channel (#7721 Phase 1). diff --git a/src/docs/release-line-guard.md b/src/docs/release-line-guard.md index 38deddb5d5..22b12d153e 100644 --- a/src/docs/release-line-guard.md +++ b/src/docs/release-line-guard.md @@ -62,9 +62,36 @@ and turns cutting `v5` into one edit that CI enforces. ## Cutting a new release line 1. Add the branch name to `release_lines` in `.github/release-lines.yml`. -2. Add it to the trigger block of every workflow listed under `pinned`. +2. Add it to the trigger block of every workflow listed under `pinned`, or + write down a `-name` exclusion with the reason. 3. Add it to every list under `env_lists` — today that is `docker.yml`'s `LONG_LIVED`, without which the new line builds but never publishes. +4. Check the pieces the guard cannot see: + - `release_lines` is also the run-time allow-list `tagged-release.yml` and + `promote-stable.yml` consult (`check-release-lines.sh --is-release-line`, + #9154). Step 1 is what lets the new line mint `vN.x.y` tags; the first + tag on a line is always `vN.0.0` (`derive-release-version.sh`). + - The new line's own copies of `tagged-release.yml`, `promote-stable.yml` + and the manifest must carry the change — `workflow_dispatch` runs read + the workflow from the dispatched ref. Forward-merge (top-up) the cut to + the new line, or land it there directly. + - `workflow_run`/`schedule` only reach the default branch's copy. The + default copy's `relay` job dispatches `tagged-release.yml --ref ` + for a non-default release line's completed build; nothing else is + needed for the new line to release automatically. + - Channel ownership is per-branch in `docker.yml`'s three + `publish-image-tags.sh` rows (`RELEASE_BRANCH INCLUDE_LATEST CHANNELS`), + on that branch. Decide which channels the new line owns; `stable` is + promoted from the default branch only. + - `changelog.d/` on the new line is consumed whole by its first release. + Every fragment must pass `check-changelog-fragment.sh` — one malformed + fragment fails `compile-changelog.sh` and therefore the decide job. + - Docs that enumerate the lines: `src/docs/releases.md`, + `src/docs/release-channels.md`, this page. + +`v6` was cut this way on 2026-11-07 — `release_lines: [v4, v5, v6]`, with +`v6` owning `edge` + `v6-latest` and `v5` keeping `candidate`, `:latest` and +`stable`. Doing only step 1 fails the guard, naming each workflow that would not run on the new branch and each list that would not publish it. That is the @@ -108,10 +135,11 @@ complete the same way: every list still naming it is reported as `unexpected`. The value takes the same `[extra]` / `[-excluded]` grammar; `mk` and `dd` are declared extras on `LONG_LIVED` — standing experimental branches that are not release lines but that a hive can be assigned to, so they legitimately publish - a tag — and so is `v6`, the development line the `edge` channel is re-based on - ([#7721](https://github.com/hivecommons/hive/issues/7721)): published, but not - a supported release line, so it is an extra here rather than a `release_lines` - entry. The value is read in any of the spellings a workflow env can take + a tag. `v6` was an extra here too while it was the development line the + `edge` channel is re-based on + ([#7721](https://github.com/hivecommons/hive/issues/7721)) — published, but + not yet a release line; since its cut it is a `release_lines` entry + instead. The value is read in any of the spellings a workflow env can take (`"v2 v4"`, unquoted, or `[v2, v4]`), with trailing comments ignored. - **That the env list is still there to check.** The variable must appear exactly once in the workflow. Zero occurrences means it was renamed or diff --git a/src/docs/releases.md b/src/docs/releases.md index 168d909e2e..f9acd54b19 100644 --- a/src/docs/releases.md +++ b/src/docs/releases.md @@ -1,42 +1,60 @@ # Tagged releases -Hive ships continuously — every merge to a release line (`v5` today) publishes moving image tags +Hive ships continuously — every merge to a release line (`v5` and `v6` today) publishes moving image tags (`-latest`, the three channels, an immutable short-SHA tag; see [release channels](release-channels.md)) with no human step. This page covers the second, **additive** layer on top of that: immutable, semver-tagged releases (`v1.2.3`) with a git tag and a GitHub Release, cut automatically — no human ever pushes a tag or clicks "Draft a release" in the normal path. -## Release lines and the v5 semver policy - -Hive has two active release lines, `v4` and `v5`, plus the `v6` development -line. Since 2026-09-21 (#7721) **`v5` is the stable line** and **`v4` is the -feature-frozen maintenance line**; each cuts its own semver tags: - -- **`v5` cuts `v5.x.y` tags.** On the `v5` branch, `tagged-release.yml` is - pinned to `v5` (trigger, concurrency group `tagged-release-v5`, release PR - base, `docker.yml` dispatch). `derive-release-version.sh` bases the next - number on the line's own latest `v5.*` tag only, and the **first** tag on a - line is always `vN.0.0` regardless of the inferred bump — the human chose - the major when they cut the line. A `v4.*` tag never seeds a `v5` number, - and vice versa. The workflow names the line explicitly (`RELEASE_LINE: v5` - on the derive step) because its checkout is a detached SHA; without that - variable on a detached checkout the script **refuses** to run rather than - falling back to the global latest tag — the fall-through that minted a - stray `v4.73.3` from `v5` on 2026-09-21 (deleted; see #7721). +## Release lines and the per-line semver policy + +Hive has three release lines, `v4`, `v5` and `v6` — the `release_lines` list +in `.github/release-lines.yml` is the single source of truth, and is also the +run-time allow-list `tagged-release.yml` consults before serving a branch +(#9154). Since 2026-09-21 (#7721) **`v5` is the stable line** and **`v4` is +the feature-frozen maintenance line**; since 2026-11-07 **`v6` is a release +line too** (it was the #7563 development line before that). Each cuts its own +semver tags: + +- **Every line cuts `vN.x.y` tags from its own branch.** `tagged-release.yml` + serves the branch it was started from (`RELEASE_LINE: ${{ github.ref_name }}` + — the default branch for `workflow_run`/`schedule`, the chosen ref for + `workflow_dispatch`) and refuses unless that branch is under + `release_lines`. `derive-release-version.sh` bases the next number on the + line's own latest `vN.*` tag only, and the **first** tag on a line is + always `vN.0.0` regardless of the inferred bump — the human chose the major + when they cut the line, so `v6`'s first release is `v6.0.0`. A `v4.*` tag + never seeds a `v5` number, and vice versa. The line is passed explicitly + because the checkout is a detached SHA; without that variable on a detached + checkout the script **refuses** to run rather than falling back to the + global latest tag — the fall-through that minted a stray `v4.73.3` from + `v5` on 2026-09-21 (deleted; see #7721). +- **`v5` cuts `v5.x.y` tags** and, as the default branch, is the only line + that receives `workflow_run` and `schedule` events directly. +- **`v6` cuts `v6.x.y` tags.** GitHub delivers `workflow_run` only to the + default branch's copy of the workflow, so the `v5` copy carries a `relay` + job: when `docker.yml` completes a push build on another declared release + line, it dispatches `tagged-release.yml --ref `, and that line's own + copy takes the backstop path (resolve the tip, require published images, + derive, release) under its own `tagged-release-` concurrency group. + The hourly schedule backstop stays default-branch only; a `v6` build that + was cancelled is picked up by its next completed build or by a manual + `gh workflow run tagged-release.yml --ref v6`. - **`v4` cuts `v4.x.y` tags** for the security and critical fixes it still - accepts under the freeze (#6346). Its copy of `tagged-release.yml` stays + accepts under the freeze (#6346). Its copy of `tagged-release.yml` is pinned to `v4` and labels its release PR `v4-freeze-exempt` so the required `freeze-gate` check lets the automated release commit land. -- **`v6` publishes continuous images only** (`v6-latest`, short-SHA, `edge`); - no `v6.x` tag exists until that line is cut as a release line. -- Channels are independent of tags: `stable`/`candidate`/`latest` follow v5 - (`stable` by digest via `promote-stable.yml`), `edge` follows v6. See - [release-channels.md](release-channels.md) and the - [digest-verifiable rollback](release-rollback.md) runbook. +- Channels are independent of tags and did **not** move with the `v6` cut: + `stable`/`candidate`/`latest` follow v5 (`stable` by digest via + `promote-stable.yml`, which only ever runs from the default branch), `edge` + and `v6-latest` follow v6, and a `v6.x.y` tag is an additional immutable + retag of the same digest. See [release-channels.md](release-channels.md) + and the [digest-verifiable rollback](release-rollback.md) runbook. -The rest of this page describes the path as it runs on `v5`; the `v4` copy -differs only in the branch name and the exempt label. +The rest of this page describes the path as it runs on `v5`; the `v6` copy is +the same file reached through the relay, and the `v4` copy differs only in +the branch name and the exempt label. ## What triggers a release @@ -168,7 +186,7 @@ errors loudly) rather than a silent pick — remove all but one. | `stable` | `promote-stable.yml`, digest promotion of the newest `v5` build that crossed the 24-hour line after the [stable soak gate](stable-soak-policy.md), while the hub stable auto-promotion toggle is playing | Yes — moving pointer | | `-latest` (`v4-latest`, `v5-latest`, `v6-latest`) | `docker.yml`, every merge to that branch | Yes — moving pointers | | `<7-hex-sha>` | `docker.yml`, every successful build | No — immutable, but not a *release* | -| `v1.2.3` | `tagged-release.yml`, only when a release is cut | No — immutable, and **is** the release | +| `v5.x.y`, `v6.x.y` | `tagged-release.yml` on that line, only when a release is cut | No — immutable, and **is** the release | `tagged-release.yml` never writes `stable`/`candidate`/`edge`. Channel promotion is a separate, deliberate policy described in diff --git a/src/scripts/check-release-lines.sh b/src/scripts/check-release-lines.sh index f28300ccbf..9a461b7ee9 100755 --- a/src/scripts/check-release-lines.sh +++ b/src/scripts/check-release-lines.sh @@ -30,13 +30,35 @@ # be assigned to the new line and the image looks healthy throughout. Green # rather than absent. # +# It also answers the one question the release workflows need at run time: +# is this branch a declared release line? tagged-release.yml and +# promote-stable.yml serve the branch they were started from +# (`github.ref_name`) rather than a hard-coded line, and refuse unless that +# branch is listed under `release_lines` here — an extra under `pinned` or +# `env_lists` (v6 as a development line, mk, dd) does not qualify. Before +# #9154 both workflows were pinned to `v5` by literal, so the copies carried +# onto `v6` would have released and promoted v5 content from a v6 dispatch, +# and nothing could ever mint a v6 tag. +# # Usage: src/scripts/check-release-lines.sh [manifest] [workflows-dir] +# src/scripts/check-release-lines.sh --is-release-line [manifest] # manifest default .github/release-lines.yml # workflows-dir default .github/workflows # -# Exit 0 = in sync, 1 = out of sync (or the inputs are unreadable). +# Exit 0 = in sync (or is a release line), 1 = out of sync (or +# is not a release line, or the inputs are unreadable), 2 = usage. set -uo pipefail +QUERY_LINE="" +if [[ "${1:-}" == "--is-release-line" ]]; then + if [[ -z "${2:-}" ]]; then + echo "ERROR: --is-release-line needs a branch name" >&2 + exit 2 + fi + QUERY_LINE="$2" + shift 2 +fi + MANIFEST="${1:-.github/release-lines.yml}" WORKFLOW_DIR="${2:-.github/workflows}" @@ -44,7 +66,7 @@ if [[ ! -f "$MANIFEST" ]]; then echo "ERROR: manifest not found at ${MANIFEST}" >&2 exit 1 fi -if [[ ! -d "$WORKFLOW_DIR" ]]; then +if [[ -z "$QUERY_LINE" && ! -d "$WORKFLOW_DIR" ]]; then echo "ERROR: workflow directory not found at ${WORKFLOW_DIR}" >&2 exit 1 fi @@ -183,6 +205,21 @@ if [[ ${#RELEASE_LINES[@]} -eq 0 ]]; then exit 1 fi +# --------------------------------------------------------------------------- +# Query mode: only `release_lines` counts. An extra (`pinned`/`env_lists`) is a +# branch CI builds or publishes, not a line that cuts tags or owns `stable`. +# --------------------------------------------------------------------------- +if [[ -n "$QUERY_LINE" ]]; then + for rl in "${RELEASE_LINES[@]}"; do + if [[ "$rl" == "$QUERY_LINE" ]]; then + echo "${QUERY_LINE} is a release line (${MANIFEST} release_lines: $(normalise "${RELEASE_LINES[@]}"))." + exit 0 + fi + done + echo "${QUERY_LINE} is not a release line (${MANIFEST} release_lines: $(normalise "${RELEASE_LINES[@]}")). Cutting it as one is the release-line cut in src/docs/release-line-guard.md, not a workflow input." >&2 + exit 1 +fi + echo "== Release-line carry-forward guard ==" echo "manifest: ${MANIFEST}" echo "workflows: ${WORKFLOW_DIR}" diff --git a/src/scripts/test-release-lines-guard.sh b/src/scripts/test-release-lines-guard.sh index 8f0f901e04..f99b16d79d 100755 --- a/src/scripts/test-release-lines-guard.sh +++ b/src/scripts/test-release-lines-guard.sh @@ -17,6 +17,9 @@ # branch filter cannot: the variable can be renamed, or defined twice, leaving # an entry that asserts nothing while the guard still prints a line about it. # +# Case 16 covers --is-release-line (#9154), the run-time allow-list the release +# workflows consult: only `release_lines` qualifies, never an extra. +# # Usage: src/scripts/test-release-lines-guard.sh set -uo pipefail @@ -266,6 +269,37 @@ expect 1 "an env_lists entry for a deleted workflow is caught" -- "$MANIFEST" "$ expect_mentions "does not exist" "the deleted workflow is explained" write_env 'LONG_LIVED: "v2 v4 mk"' +# --------------------------------------------------------------------------- +# 16. --is-release-line (#9154): the run-time allow-list tagged-release.yml and +# promote-stable.yml consult before serving `github.ref_name`. Only +# `release_lines` qualifies. v6 is modelled as it stands before its GA +# cut — an extra on a pinned workflow AND on the push-policy list — and +# must still be refused: a branch CI builds and publishes is not a branch +# that cuts vN.x.y tags or owns `stable`. Refusing it is what stops a +# development line's dispatch from releasing, and adding it to +# `release_lines` is the single edit that turns its release path on. +# --------------------------------------------------------------------------- +QMANIFEST="${TMP}/query-manifest.yml" +cat > "$QMANIFEST" <<'EOF' +release_lines: [v4, v5] +pinned: + flow-form.yml: [v6] +env_lists: + envy.yml LONG_LIVED: [mk, v6] +EOF +expect 0 "a declared release line is accepted" -- --is-release-line v5 "$QMANIFEST" +expect 0 "every declared release line is accepted, not just the last" -- --is-release-line v4 "$QMANIFEST" +expect 1 "a pinned/env-list extra (pre-GA v6) is refused" -- --is-release-line v6 "$QMANIFEST" +expect_mentions "v6 is not a release line" "the refusal names the branch" +expect_mentions "v4,v5" "the refusal names the declared release lines" +expect 1 "a standing experimental branch that publishes (mk) is refused" -- --is-release-line mk "$QMANIFEST" +expect 1 "a feature branch is refused" -- --is-release-line feat/v5-thing "$QMANIFEST" +expect 1 "a prefix of a release line is not a match" -- --is-release-line v "$QMANIFEST" +expect 1 "an unreadable manifest refuses rather than allowing" -- --is-release-line v5 "${TMP}/no-such-manifest.yml" +expect 2 "a missing branch argument is a usage error, not an allow" -- --is-release-line "" "$QMANIFEST" +sed -E 's/^(release_lines: \[[^]]*)\]/\1, v6]/' "$QMANIFEST" > "${TMP}/query-cut-manifest.yml" +expect 0 "the GA cut (adding v6 to release_lines) is what admits v6" -- --is-release-line v6 "${TMP}/query-cut-manifest.yml" + echo if [[ $fail -ne 0 ]]; then echo "RESULT: FAIL — the release-line guard is not detecting what it claims to." From ec9865441917d2b417b519ace7fa9382aea41551 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Sat, 7 Nov 2026 14:07:04 -0500 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=96=20docs:=20full=20release-line?= =?UTF-8?q?=20cut=20checklist,=20ROADMAP=20line=20table=20for=20v6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- ROADMAP.md | 2 +- src/docs/release-line-guard.md | 108 +++++++++++++++++++-------------- 2 files changed, 63 insertions(+), 47 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 9c00fb72cf..e421d99eba 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -16,7 +16,7 @@ plan (Now / Next / Later, item by item), see the | --- | --- | --- | --- | | v4 | `v4` | Maintenance line (feature-frozen; security/critical fixes only) | none — builds publish `v4-latest` and short-SHA tags only ([#7721](https://github.com/hivecommons/hive/issues/7721) Phase 1) | | v5 | `v5` (default) | Supported stable line since the 2026-09-21 cut-over | `stable`, `candidate`, `latest` | -| v6 | `v6` | Active development, tracks v5 by forward-merge; the #7563 dashboard-optional tracks are merged on the branch (see [v6 section](#v6--dashboard-optional-operation-line-open)) | `edge` | +| v6 | `v6` | Release line since 2026-11-07 (cuts `v6.x.y` tags, GitHub Releases and SBOMs from the branch; first tag `v6.0.0`); tracks v5 by forward-merge, and the #7563 dashboard-optional tracks are merged on the branch (see [v6 section](#v6--dashboard-optional-operation-line-open)) | `edge` (plus `v6-latest`); `stable`/`candidate`/`latest` stay on v5 | Operators select a line by pointing a hive at a [release channel](src/docs/release-channels.md) rather than a branch tag. diff --git a/src/docs/release-line-guard.md b/src/docs/release-line-guard.md index 22b12d153e..ddcc5068aa 100644 --- a/src/docs/release-line-guard.md +++ b/src/docs/release-line-guard.md @@ -66,52 +66,67 @@ and turns cutting `v5` into one edit that CI enforces. write down a `-name` exclusion with the reason. 3. Add it to every list under `env_lists` — today that is `docker.yml`'s `LONG_LIVED`, without which the new line builds but never publishes. -4. Check the pieces the guard cannot see: - - `release_lines` is also the run-time allow-list `tagged-release.yml` and - `promote-stable.yml` consult (`check-release-lines.sh --is-release-line`, - #9154). Step 1 is what lets the new line mint `vN.x.y` tags; the first - tag on a line is always `vN.0.0` (`derive-release-version.sh`). - - The new line's own copies of `tagged-release.yml`, `promote-stable.yml` - and the manifest must carry the change — `workflow_dispatch` runs read - the workflow from the dispatched ref. Forward-merge (top-up) the cut to - the new line, or land it there directly. - - `workflow_run`/`schedule` only reach the default branch's copy. The - default copy's `relay` job dispatches `tagged-release.yml --ref ` - for a non-default release line's completed build; nothing else is - needed for the new line to release automatically. - - Channel ownership is per-branch in `docker.yml`'s three - `publish-image-tags.sh` rows (`RELEASE_BRANCH INCLUDE_LATEST CHANNELS`), - on that branch. Decide which channels the new line owns; `stable` is - promoted from the default branch only. - - `changelog.d/` on the new line is consumed whole by its first release. - Every fragment must pass `check-changelog-fragment.sh` — one malformed - fragment fails `compile-changelog.sh` and therefore the decide job. - - Docs that enumerate the lines: `src/docs/releases.md`, - `src/docs/release-channels.md`, this page. - -`v6` was cut this way on 2026-11-07 — `release_lines: [v4, v5, v6]`, with -`v6` owning `edge` + `v6-latest` and `v5` keeping `candidate`, `:latest` and -`stable`. - -Doing only step 1 fails the guard, naming each workflow that would not run on -the new branch and each list that would not publish it. That is the -demonstration -`src/scripts/test-release-lines-guard.sh` performs in CI, against the real -workflow files: - -``` -FAIL: v2-ci.yml:5 branches: has [v2,v4], expected [v2,v4,v5] — missing: v5. - A release line named here but absent from the workflow means that - workflow does not run on it at all. -FAIL: docker.yml:56 env LONG_LIVED: has [dd,mk,v2,v4], expected - [dd,mk,v2,v4,v5] — missing: v5. This list is not a trigger, so a release - line missing from it fails GREEN: the image still builds on that branch - and simply never publishes its -latest tag, leaving no image for - a hive to be assigned to. -``` - -The check is an equality in both directions, so *retiring* a line is proven -complete the same way: every list still naming it is reported as `unexpected`. +Those three steps are what the guard enforces. They are not the whole cut: a +release line also cuts `vN.x.y` tags and, when it becomes the stable line, +owns the `candidate`/`latest`/`stable` channels. The v4→v5 cut +([#7721](https://github.com/hivecommons/hive/issues/7721)) did the rest by +hand-editing the release workflows, and the edited copies were then carried +onto `v6` still naming `v5` +([#9154](https://github.com/hivecommons/hive/issues/9154)). The full cut, on +the new line's branch unless noted: + +4. **Tag path — no edit.** `tagged-release.yml` and `promote-stable.yml` serve + the branch they were started from (`github.ref_name`) and refuse unless + that branch is under `release_lines` + (`src/scripts/check-release-lines.sh --is-release-line `). Step 1 + is what turns them on for the new line; before it, a dispatch from that + branch fails at its first step instead of releasing or promoting another + line. The check reads the script and manifest from the workflow's own + ref, before the commit being released is checked out, and + `tagged-release.yml` accepts a `docker.yml` run only when it was a `push` + or `workflow_dispatch`, so a fork PR whose branch is named after a release + line cannot approve itself. `derive-release-version.sh` mints `vN.0.0` as + the first tag of a line on its own. Do **not** reintroduce a literal + branch name in either workflow. +5. **Carry the cut to the new line's branch.** `workflow_dispatch` runs read + the workflow, the manifest and the scripts from the dispatched ref, so the + new line's own copies of `.github/release-lines.yml`, + `tagged-release.yml`, `promote-stable.yml` and `check-release-lines.sh` + must have the change too — forward-merge (top-up) it, or land it there + directly. Until then the new line's copy still refuses. +6. **Non-default lines release through the relay.** `schedule` and + `workflow_run` triggers only fire from the repository's default branch, so + the hourly backstop and the hourly `stable` promotion follow it. The + default copy of `tagged-release.yml` carries a `relay` job: when + `docker.yml` completes a `push`/`workflow_dispatch` build on another + declared release line, it dispatches `tagged-release.yml --ref `, + and that line's own copy takes the backstop path (resolve the tip, require + published images, compile fragments, derive, release). That is how `v6` + releases on every merge without being the default branch. A build that + was cancelled on a non-default line is picked up by its next completed + build or by a manual dispatch from that branch; the schedule does not + relay. +7. **Channels — `docker.yml` on both branches, landed together.** Each + branch's copy names its own channels in the three `publish-image-tags.sh` + calls (` `) and the matching + `INCLUDE_LATEST` / `RELEASE_BRANCH` / `CHANNELS` env on the three + cross-org mirror steps. The stable line takes `true candidate` (candidate + plus `:latest`); flipping one branch without the other leaves two lines + retagging `candidate` and `:latest` on every merge. `stable` is promoted + from the default branch only, and `candidate` is one repository-wide tag, + so `promote-stable.yml` must not be dispatched from a line that does not + own it. Cutting a line as a *release* line and moving the *channels* to it + are separate decisions: `v6` was cut on 2026-11-07 keeping `edge` + + `v6-latest`, while `v5` kept `candidate`, `:latest` and `stable`. +8. **The first release consumes the whole `changelog.d/` backlog.** A new + line's `## Unreleased` has never been emptied, so its first release + compiles every fragment it has accumulated. Every one must pass + `check-changelog-fragment.sh`: a single malformed fragment fails + `compile-changelog.sh` and therefore the decide job, and no tag is cut. +9. **Docs.** Update [releases.md](releases.md#release-lines-and-the-per-line-semver-policy) + §Release lines, [release-channels.md](release-channels.md) (which branch + publishes which channel), the branch table in `CONTRIBUTING.md`, and the + line policy in `ROADMAP.md`. ## What it checks @@ -227,4 +242,5 @@ guard proves the edit is complete. See the note at the bottom of ```sh src/scripts/check-release-lines.sh # assert the repository is in sync src/scripts/test-release-lines-guard.sh # prove the checker still fails when it should +src/scripts/check-release-lines.sh --is-release-line v6 # may the release workflows serve v6? (exit 0 = yes) ``` From a8eea8e14c313a4ac682161d0a94fd1f15f7ce0e Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Sat, 7 Nov 2026 14:11:53 -0500 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=96=20docs:=20repoint=20releases.m?= =?UTF-8?q?d=20anchor=20after=20section=20rename?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- src/docs/release-rollback.md | 2 +- src/docs/v5-ga.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/release-rollback.md b/src/docs/release-rollback.md index 6d799c53d0..18a1cafff7 100644 --- a/src/docs/release-rollback.md +++ b/src/docs/release-rollback.md @@ -25,7 +25,7 @@ immutable vs. moving" in [releases.md](releases.md)): | Reference | Written by | Notes | |---|---|---| | `ghcr.io/hivecommons/:<7-hex-sha>` | `docker.yml`, every successful build of a release line | Retained for a bounded window: the scheduled GHCR prune deletes package versions whose only tags are short-SHA tags after **90 days** (`RETENTION_DAYS` in `.github/workflows/prune-ghcr*.yml`). Versions still carrying any moving tag are never pruned. | -| `ghcr.io/hivecommons/:v` | `tagged-release.yml`, only when a release is cut | A retag of the short-SHA digest, byte-identical to it, not subject to the 90-day prune. `v4` line only today; see the [v5 semver policy](releases.md#release-lines-and-the-v5-semver-policy). | +| `ghcr.io/hivecommons/:v` | `tagged-release.yml`, only when a release is cut | A retag of the short-SHA digest, byte-identical to it, not subject to the 90-day prune. `v5.x.y` and `v6.x.y` (and `v4.x.y` under the freeze); see the [per-line semver policy](releases.md#release-lines-and-the-per-line-semver-policy). | | `ghcr.io/hivecommons/@sha256:` | You, in the deployment manifest | The digest form is what this runbook actually writes. A tag is how you *find* the digest; the digest is what you *pin*. | The three images are **separate build jobs** tagged with the same short SHA, diff --git a/src/docs/v5-ga.md b/src/docs/v5-ga.md index 7972a7c5ed..229e593ca3 100644 --- a/src/docs/v5-ga.md +++ b/src/docs/v5-ga.md @@ -19,7 +19,7 @@ cannot be counted as complete. | Required build/test gate | **Accepted 2026-09-09 ([#6171](https://github.com/hivecommons/hive/issues/6171) closed as decided):** the protected release-line gate for `v5` has been green for 7 consecutive days, with no ignored required checks. A red required check on the protected branch restarts the window; a concurrency-cancelled run does not count as red ([#6293](https://github.com/hivecommons/hive/issues/6293)). | GitHub branch protection/check history for `v5`. Branch protection currently requires the `gate` context from `docker.yml` / **Build and Push Docker Image**; re-check with `unset GITHUB_TOKEN && gh api repos/hivecommons/hive/branches/v5/protection --jq '.required_status_checks.contexts'`. Check run evidence can come from `gh api repos/hivecommons/hive/commits/v5/check-runs` or `gh run list --branch v5 --workflow docker.yml --limit N --json conclusion,createdAt,url,headSha`. | **Evidence-ready:** the 7-day window elapsed 2026-09-10T11:25Z on the `gate` context. Window start is 2026-09-03T11:25:39Z (`f80698e2`) — the first green run after the last red, 2026-09-03T10:02:31Z (`cbd39972`, [run 33742150760](https://github.com/hivecommons/hive/actions/runs/33742150760)), which restarted the window per the accepted rule. Re-measured 2026-09-14: **zero** `failure` runs since that restart across 190 sampled `docker.yml` runs on `v5` spanning 2026-08-18 to 2026-09-14T09:44Z, so the streak now stands at ~11 days; cancelled-by-concurrency runs ignored per [#6293](https://github.com/hivecommons/hive/issues/6293); evidence recorded in [#6808](https://github.com/hivecommons/hive/issues/6808). Row closes when a maintainer records the evidence bullet on [#6016](https://github.com/hivecommons/hive/issues/6016) — note this arms the v4 feature-freeze trigger once all Release-train rows are green. | | v5 channel publication | Every successful `v5` Docker build publishes immutable short-SHA image tags and moves only the `edge` channel; `stable`/`candidate` remain v4 until a promotion policy lands. | `docker.yml` run summary and GHCR manifests for `ghcr.io/hivecommons/hive`, `hive-contributor`, and `hive-hub`; compare `edge` digest to the `v5-latest`/short-SHA digest. | **Evidence-ready pending candidate designation:** on 2026-09-14 the `edge` digest equalled the `v5-latest` digest for all three images, and `candidate` remained pinned to `v4-latest` ([#6887](https://github.com/hivecommons/hive/issues/6887)). The remaining check — `edge` vs the GA candidate's short-SHA tag — cannot run until a maintainer designates the GA candidate SHA on [#6016](https://github.com/hivecommons/hive/issues/6016). | | Digest-verifiable rollback | Operators can resolve the GA candidate and rollback targets to immutable digests for all three images. | GHCR manifest inspection for the GA candidate's short-SHA tag and the documented rollback/channel-switch procedure. | **Procedure documented:** the digest-verifiable rollback/channel-switch runbook landed as [`release-rollback.md`](release-rollback.md) via [#6266](https://github.com/hivecommons/hive/pull/6266) (merged 2026-09-08), covering all three images and digest pinning/verification. Row closes when GHCR manifest inspection is run for the GA candidate's short-SHA tag and recorded on [#6016](https://github.com/hivecommons/hive/issues/6016). | -| Tagged release docs | The tagged-release path documents whether semver tags are cut from `v5`, still cut only from `v4`, or deliberately deferred for the v5 GA candidate. | `src/docs/releases.md` and the tagged-release workflow triggers. | **Policy documented:** [`releases.md`](releases.md#release-lines-and-the-v5-semver-policy) now states the v5 semver policy — semver tags are cut from `v4` only, `v5` publishes continuous images, and a `v5` semver line is deliberately deferred until this GA bar closes ([#6266](https://github.com/hivecommons/hive/pull/6266), merged 2026-09-08). Row closes when a maintainer records this on [#6016](https://github.com/hivecommons/hive/issues/6016). | +| Tagged release docs | The tagged-release path documents whether semver tags are cut from `v5`, still cut only from `v4`, or deliberately deferred for the v5 GA candidate. | `src/docs/releases.md` and the tagged-release workflow triggers. | **Policy documented:** [`releases.md`](releases.md#release-lines-and-the-per-line-semver-policy) now states the v5 semver policy — semver tags are cut from `v4` only, `v5` publishes continuous images, and a `v5` semver line is deliberately deferred until this GA bar closes ([#6266](https://github.com/hivecommons/hive/pull/6266), merged 2026-09-08). Row closes when a maintainer records this on [#6016](https://github.com/hivecommons/hive/issues/6016). | | Migration guide | A v4-to-v5 migration guide exists and names supported prerequisites, data/config compatibility, downgrade/rollback limits, and the channel choice operators should use during migration. | The merged migration guide (for example `UPGRADE.md` or a docs page linked from `src/docs/documentation-map.md`). | Guide exists: [`UPGRADE.md`](../../UPGRADE.md) landed via #5559 and is linked from `src/docs/documentation-map.md`; row closes when maintainers confirm it covers the GA candidate's prerequisites and rollback limits. | | Dual-version validation | **Bound — maintainer-recorded decision, see [#6112](https://github.com/hivecommons/hive/issues/6112):** at least one documented validation run covers v4 and v5 hub/spoke operation during transition, including heartbeat, branch/channel switching, and rollback expectations. No automated dual-version test exists today — `podman-contract.yml` runs only `v2`; `v2-ci.yml`/`v2-tests.yml` cover a single line at a time — so the row is evidenced by a dated manual run record until CI grows one. | Owner: maintainers (**@clubanderson**), with the ci-maintainer lane collecting the evidence comment on [#6016](https://github.com/hivecommons/hive/issues/6016). Evidence bullet format: `Evidence (YYYY-MM-DD, recorder): hub image tag: ; spoke image tag: ; scenario: ; hive status/heartbeat output: ; conclusion: pass/fail.` Gap: no CI artifact backs this row; see the [Dual-version validation exercise](#dual-version-validation-exercise-bound) subsection below. | Bound; not yet run. Closes when the first evidence bullet is posted on #6016. | | Reviewer lane production exercise | **Bound — maintainer-recorded decision, see [#6130](https://github.com/hivecommons/hive/issues/6130):** one reviewer-lane (review swarm, [`src/docs/review-swarm.md`](review-swarm.md)) PR on `hivecommons/hive` is processed end-to-end in production — review posted by the lane and merged by a human — scheduled during the GA candidate week. | The PR URL, the lane's review-verdict comment URL, and the governor dispatch/`review-verdicts.json` artifact, linked from [#6016](https://github.com/hivecommons/hive/issues/6016); plus the #5617 tracker closure state (closed 2026-09-03). A maintainer triggers the exercise by kicking the reviewer-capable agent from the dashboard (`POST /api/kick/`) against the candidate PR. | Bound; not yet scheduled. Closes when the PR/comment/artifact links are posted on #6016. | From 30c64c75c10186d588ecedb9dd8a848173c2f12d Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Sat, 7 Nov 2026 14:23:32 -0500 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=8C=B1=20ci:=20carry=20v6's=20test-re?= =?UTF-8?q?lease-push-retry.sh=20(push=5Fline=20step=20id)=20into=20v5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The parameterised tagged-release.yml renames push_v5 to push_line; the contract test must follow. Re-pins TRUSTED_SCRIPTS_TREE. Signed-off-by: Andrew Anderson --- .github/scripts/integration-governance.cjs | 2 +- src/scripts/test-release-push-retry.sh | 60 ++++++++++++---------- 2 files changed, 34 insertions(+), 28 deletions(-) diff --git a/.github/scripts/integration-governance.cjs b/.github/scripts/integration-governance.cjs index ad2ede5bcb..a4744dee2c 100644 --- a/.github/scripts/integration-governance.cjs +++ b/.github/scripts/integration-governance.cjs @@ -9,7 +9,7 @@ const MAX_COMMITS = 1000; const MAX_AUTHOR_BATCH = 50; // This literal is inside the enrolled .github closure. A caller-supplied // preparedBy.sourceSHA must never choose a new executable verifier tree. -const TRUSTED_SCRIPTS_TREE = 'e7c942c022e901723f7b629550e1dc9309858ffa'; +const TRUSTED_SCRIPTS_TREE = 'e8a3da340e5a6084d5b551d1052b0258468d5640'; const SOURCE = 'https://github.com/kubernetes-sigs/kubebuilder-release-tools/tree/012269a88fa4c034a0acf1ba84c26b195c0dbab4'; const sha = value => crypto.createHash('sha256').update(value).digest('hex'); const git = (args, cwd = process.cwd()) => diff --git a/src/scripts/test-release-push-retry.sh b/src/scripts/test-release-push-retry.sh index 8cf0863c73..e29a885ee0 100755 --- a/src/scripts/test-release-push-retry.sh +++ b/src/scripts/test-release-push-retry.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# test-release-push-retry.sh — exercises the `push_v5` step of +# test-release-push-retry.sh — exercises the `push_line` step of # .github/workflows/tagged-release.yml (#5142, #5222) by extracting its script # from the workflow file itself and driving it with stubbed `git`/`gh`, so the # merge state machine is proven against the shipped source rather than a copy. @@ -57,15 +57,15 @@ if ! python3 -c 'import yaml' 2>/dev/null; then fi # --- extract the step's script verbatim from the workflow --------------------- -python3 - "$workflow" > "$tmp/push_v5.sh" <<'PY' +python3 - "$workflow" > "$tmp/push_line.sh" <<'PY' import sys, yaml w = yaml.safe_load(open(sys.argv[1])) for st in w["jobs"]["release"]["steps"]: - if st.get("id") == "push_v5": + if st.get("id") == "push_line": sys.stdout.write(st["run"]) break else: - sys.exit("no step with id push_v5 in the release job") + sys.exit("no step with id push_line in the release job") PY # --- stub git + gh + sleep ----------------------------------------------------- @@ -200,9 +200,10 @@ run_step() { RPR_SCENARIO="$1" RPR_TAG_SCENARIO="${2:-ok}" RPR_STATE="$st" \ RELEASE_MERGE_WAIT_SECONDS="${3:-120}" RELEASE_MERGE_POLL_SECONDS=8 \ VERSION="4.0.1" SHA="deadbeefcafe" GITHUB_OUTPUT="$st/gh_output" \ + RELEASE_LINE="v5" \ ACTIONS_TOKEN="actions-token-for-test" \ GITHUB_REPOSITORY="hivecommons/hive" \ - PATH="$tmp/bin:$PATH" bash "$tmp/push_v5.sh" > "$st/out" 2>&1 + PATH="$tmp/bin:$PATH" bash "$tmp/push_line.sh" > "$st/out" 2>&1 rc=$? output=$(cat "$st/out") ghout=$(cat "$st/gh_output" 2>/dev/null || true) @@ -338,7 +339,7 @@ gh_release = next((s for s in rel.get("steps", []) if "Create GitHub Release" in (s.get("name") or "")), None) if gh_release is None: bad("the Create GitHub Release step was not found") -elif "steps.push_v5.outputs.pushed == 'true'" not in (gh_release.get("if") or ""): +elif "steps.push_line.outputs.pushed == 'true'" not in (gh_release.get("if") or ""): bad("Create GitHub Release is not gated on pushed=true — a deferred run would " "publish a Release for a tag that was never pushed") perms = w.get("permissions", {}) @@ -404,20 +405,25 @@ else: guard_run = guard.get("run") or "" # #6380: the exact-SHA docker.yml handoff is a workflow_dispatch run on v5, # not a push. The backstop may count that publishing run. #10866 also - # needs a backstop-primed v5 workflow_dispatch docker run to re-enter this - # workflow once the images exist; post-release handoffs are harmless - # because Unreleased is empty by then. - if '.event == "workflow_dispatch"' not in guard_run or '.head_branch == "v5"' not in guard_run: - bad("the backstop no longer accepts v5 workflow_dispatch docker.yml publishing runs (#6380)") - if 'gh workflow run docker.yml --ref v5' not in guard_run: - bad("the backstop no longer primes docker.yml when v5 tip images are missing (#10866)") + # needs a backstop-primed workflow_dispatch docker run on the line to + # re-enter this workflow once the images exist; post-release handoffs are + # harmless because Unreleased is empty by then. + if '.event == \\"workflow_dispatch\\"' not in guard_run or '.head_branch == \\"${RELEASE_LINE}\\"' not in guard_run: + bad("the backstop no longer accepts the release line's workflow_dispatch docker.yml publishing runs (#6380)") + if 'gh workflow run docker.yml --ref "$RELEASE_LINE"' not in guard_run: + bad("the backstop no longer primes docker.yml when the release line's tip images are missing (#10866)") decide_if = dec.get("if") or "" if "github.event.workflow_run.event != 'workflow_dispatch'" in decide_if: - bad("decide still rejects v5 workflow_dispatch docker completions, so a backstop-primed image build cannot release (#10866)") + bad("decide still rejects workflow_dispatch docker completions on the line, so a backstop-primed image build cannot release (#10866)") + if ("github.event.workflow_run.event == 'push'" not in decide_if + or "github.event.workflow_run.event == 'workflow_dispatch'" not in decide_if + or "github.event.workflow_run.head_branch == github.ref_name" not in decide_if): + bad("decide must admit only push/workflow_dispatch workflow_run events on the release line itself — " + "a pull_request run's head_branch is fork-controlled (#9154)") push_step = next((s for s in rel.get("steps", []) - if s.get("id") == "push_v5"), None) + if s.get("id") == "push_line"), None) if push_step is None: - bad("no step with id push_v5 found") + bad("no step with id push_line found") else: run = push_step.get("run", "") # Comments in this step DISCUSS `gh pr merge` (explaining why it was @@ -425,18 +431,18 @@ else: code = "\n".join(l for l in run.splitlines() if not l.lstrip().startswith("#")) if "gh pr create" not in code: - bad("push_v5 no longer merges via a PR (#5222) — check for a regression back to a raw v5 push") + bad("push_line no longer merges via a PR (#5222) — check for a regression back to a raw v5 push") if "/merge" not in code or "gh api -X PUT" not in code: - bad("push_v5 no longer merges via the SHA-keyed merge API (#5318/#5324)") + bad("push_line no longer merges via the SHA-keyed merge API (#5318/#5324)") if '-f sha="${commit_sha}"' not in code: bad("the merge API call no longer passes -f sha= — without it a mid-flight " "head move merges the wrong tree instead of deferring (#5318/#5324)") if "${{" in code: - bad("push_v5's code uses a ${{ }} expression — this step is extracted and run under " + bad("push_line's code uses a ${{ }} expression — this step is extracted and run under " "plain bash by this test, where that is a bad-substitution. Use the runner's " "environment variables (e.g. $GITHUB_REPOSITORY) instead.") if "gh pr merge" in code: - bad("push_v5 regressed to `gh pr merge`, which refuses any PR whose AGGREGATE " + bad("push_line regressed to `gh pr merge`, which refuses any PR whose AGGREGATE " "mergeStateStatus is BLOCKED — a pending non-required `tide` status alone is " "enough to block every release forever (#5318/#5324)") # #5356: workflow_dispatch check-runs are not PR-associated, even when @@ -444,28 +450,28 @@ else: # SHA-scoped commit status BEFORE opening the PR so its rollup can see it. status_endpoint = 'repos/${GITHUB_REPOSITORY}/statuses/${commit_sha}' if status_endpoint not in code: - bad("push_v5 no longer publishes the SHA-scoped gate status — the release PR " + bad("push_line no longer publishes the SHA-scoped gate status — the release PR " "rollup cannot see workflow_dispatch check-runs and protection 405s (#5356)") else: status_at = code.index(status_endpoint) pr_at = code.index("gh pr create") merge_at = code.index("gh api -X PUT") if not status_at < pr_at < merge_at: - bad("push_v5 must publish gate status, then open the PR, then merge it (#5356)") + bad("push_line must publish gate status, then open the PR, then merge it (#5356)") if "-f state=success" not in code or "-f context=gate" not in code: - bad("push_v5's commit status is not the required gate:success verdict (#5356)") + bad("push_line's commit status is not the required gate:success verdict (#5356)") if "RELEASE_MERGE_WAIT_SECONDS" not in code or ":-300" not in code: - bad("push_v5 no longer waits up to the 5-minute release merge deadline (#10863)") + bad("push_line no longer waits up to the 5-minute release merge deadline (#10863)") if "required_checks_state" not in code: - bad("push_v5 no longer polls the release PR's required checks before giving up (#10795)") + bad("push_line no longer polls the release PR's required checks before giving up (#10795)") # #6380: a release PR merged with GITHUB_TOKEN cannot emit docker.yml's # push event. Dispatch immediately after the SHA-keyed merge, before tag # retries widen the window in which a later v5 push could get an earlier # docker.yml run number. The exact merge SHA must be an explicit input. merge_at = code.index("gh api -X PUT") - dispatch_call = "gh workflow run docker.yml --ref v5" + dispatch_call = 'gh workflow run docker.yml --ref "$RELEASE_LINE"' if dispatch_call not in code: - bad("push_v5 no longer dispatches docker.yml after the GITHUB_TOKEN merge (#6380)") + bad("push_line no longer dispatches docker.yml after the GITHUB_TOKEN merge (#6380)") else: dispatch_at = code.rindex(dispatch_call) tag_at = code.index('git tag "v${VERSION}"')