Skip to content

Latest commit

 

History

History
627 lines (556 loc) · 37.2 KB

releases.md

File metadata and controls

627 lines (556 loc) · 37.2 KB

Tagged releases

Hive ships continuously — every merge to a release line (v5 and v6 today) publishes moving image tags (<branch>-latest, the three channels, an immutable short-SHA tag; see release channels) 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 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 <line>, and that line's own copy takes the backstop path (resolve the tip, require published images, derive, release) under its own tagged-release-<line> 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 is pinned to v4 and labels its release PR v4-freeze-exempt so the required freeze-gate check lets the automated release commit land.
  • 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 and the digest-verifiable rollback runbook.

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

.github/workflows/tagged-release.yml runs after every successful Build and Push Docker Image (docker.yml) run on v5 — a workflow_run trigger, not a tag push, because there is no tag until this workflow decides to create one. It never runs for v2, mk, dd, or a manual workflow_dispatch build.

It also runs hourly on a schedule, as a backstop (#5318). The workflow_run trigger alone can silently lose a release opportunity: a docker.yml run that is cancelled never fires workflow_run at all, and GitHub's concurrency queue holds at most one pending run per group, so on a busy branch most commits never complete a build. The scheduled pass walks v5's recent history from the tip and considers the newest commit that has a successful, completed publishing docker.yml run — not necessarily the tip itself, which on a busy branch is rarely built yet. It retags that commit's existing digests exactly as the normal path does, so a cancelled or in-flight build never produces a tag with no digest behind it; if nothing recent is built it stands down green and dispatches docker.yml for the tip. It is a no-op whenever ## Unreleased is empty — which on a healthy repository is almost always.

The tag names the commit the images were built from, not v5's tip. The release commit (compiled CHANGELOG.md plus the fragment deletions) is parented on the exact SHA docker.yml built, the v<version> tag points at that release commit, and the immutable image tags are retags of that SHA's digests. The release commit reaches v5 through a merge-commit PR that is allowed to land on a tip that has moved on — the merge commit is not tagged, so commits that arrived after the built SHA are "after v<version>" in git exactly as they are in image terms. Until 2026-11 the workflow instead deferred whenever v5 had advanced past the built SHA, expecting the successor run to release; with merges arriving faster than a multi-arch build no run ever saw an unmoved tip, every successor deferred again, and v5 went from v5.186.4 (2026-10-18) to ~1,700 untagged commits before the rule was changed. The two remaining deferrals — logged as warnings so a skipped opportunity is visible — are the cases where tagging the built SHA really would be wrong: the built SHA is no longer an ancestor of v5's tip, or a release already landed after it (the newest v5.* tag is not an ancestor of the built SHA, so its fragments are already released and the derived version would collide).

Before anything is decided, src/scripts/compile-changelog.sh folds any changelog.d/ fragment files — the per-PR entry files that replaced direct ## Unreleased appends (#5675) — into the ## Unreleased section of the working tree, grouped under the ### subsection their filename prefix names. src/scripts/derive-release-version.sh then decides two things by reading CHANGELOG.md's ## Unreleased section — nothing else, no commit-message parsing:

  • Empty ## Unreleased (the common case — most merges are docs, tests, CI, or refactors) → no release. Silent, correct, no tag, no GitHub Release, nothing published beyond the continuous images that already went out.
  • Non-empty → a release is cut, with the bump taken from which ### subsection headers are present:
    • ### Security present → major
    • else ### Added present → minor
    • else (### Changed / ### Fixed / ### Deprecated only) → patch

Why CHANGELOG.md and not the emoji commit-prefix convention

CONTRIBUTING.md asks PR titles to start with an emoji (🐛 fix, ✨ feature, 📖 docs, …), which looks like a ready-made conventional-commit signal. It is not enforced — plenty of merged commits on v5 carry no emoji at all — so inferring a published, immutable version number from it would mean an unlabeled fix silently produces the wrong shape of release, or a missing prefix produces no release at all, with nobody watching each merge to catch it. CHANGELOG.md's ## Unreleased section is already the human, PR-time judgment call for "is this release-worthy" (CONTRIBUTING.md and .github/workflows/changelog-reminder.yml already ask for and nudge entries there), and getting it wrong fails safe: a missed entry means no release fires, never a released version with the wrong number. See the script's own header comment for the full reasoning.

The commit convention IS the interface

This is the one thing a contributor needs to know to cause a release, and it is nothing new — it is the existing changelog convention, now load-bearing:

  • Add a changelog.d/<category>-<pr-or-slug>.md fragment in your PR (as CONTRIBUTING.md asks, nudged by the changelog-reminder and changelog-fragment-guard checks) if your change is user-visible. The file's content is exactly your entry — one - bullet; see changelog.d/README.md.
  • The filename's category prefix picks the subsection your entry is compiled into (added- → ### Added, and so on for changed/deprecated/fixed/ security), and the subsections drive the bump exactly as they always have. Existing ## Unreleased entries still compose with fragments, but the transition window for direct edits closed on 2026-09-09 (#5675): every PR editing that one shared heading is what made unrelated PRs conflict, so new PRs use fragments instead.
  • If your PR carries no fragment (and no CHANGELOG.md edit), it contributes to whatever release fires next but does not by itself trigger one — and if Unreleased and changelog.d/ are otherwise empty, no release fires until someone's entry lands.

You do not choose a version number. You choose a changelog section, and the version follows from semver rules applied to whatever is sitting in Unreleased when the next merge to v5 completes its build.

The escape hatch

Inference will occasionally be wrong — an entry filed under the wrong heading, or a change a maintainer wants held back. A single HTML-comment marker anywhere in the ## Unreleased section overrides the inferred decision:

<!-- release: none -->

suppresses a release for this merge even if Unreleased has content (the entries stay queued for the next release that does fire). Note the consequence under the fragment model: nothing but a release empties Unreleased, so a none marker placed there (by hand, in CHANGELOG.md) is a release freeze that lasts until a human removes it, not a one-merge skip — the decide job emits a ::warning:: annotation on every run while it is in force, and fails outright once the newest tag is older than RELEASE_FREEZE_MAX_DAYS (default 7; 0 disables) so a forgotten freeze turns red instead of looking like a healthy no-op. For the same reason the marker is rejected in a changelog.d/ fragment by check-changelog-fragment.sh and compile-changelog.sh: a fragment lives until the release that consumes it, so a none fragment can never be consumed and vetoes every later merge (#12928 stalled v5 releases from 2026-10-19 to 2026-11-07 this way). A change that should not be mentioned wants no fragment and the no-changelog label. Or force a specific bump regardless of which headers are present:

<!-- release: major -->
<!-- release: minor -->
<!-- release: patch -->

Two conflicting markers in the same section is a hard failure (the workflow errors loudly) rather than a silent pick — remove all but one.

What is immutable vs. moving

Tag Written by Moves?
candidate, latest docker.yml, every merge to v5 Yes — moving pointers
edge docker.yml, every merge to v6 Yes — moving pointer
stable promote-stable.yml, digest promotion of the newest v5 build that crossed the 24-hour line after the stable soak gate, while the hub stable auto-promotion toggle is playing Yes — moving pointer
<branch>-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
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 release-channels.md; cutting a version tag never silently couples to it, on purpose — the operator explicitly asked for these to stay decoupled.

Hub-managed hives on the candidate channel follow their stored auto-upgrade cadence (auto_upgrade_mode: daily by default, weekly, or instant) just like stable hives (#11816). A daily candidate hive therefore picks up the newest published candidate image once a day, in the first poll at or after 1pm ET; the hub reports the hold as upgradeWhyNotNow: "before the daily window" and the spoke's /api/version shows state: behind until then. To track every published candidate image, set the hive's mode to instant (PUT /api/saas/hives/{id}/auto-upgrade with {"auto_upgrade": true, "auto_upgrade_mode": "instant"}, or the Manage → Auto-upgrade control on the hub). Setting HIVE_CANDIDATE_RESPECT_AUTO_UPGRADE_SCHEDULE=false on the hub restores the old behaviour where every candidate hive bypasses its cadence.

The hub itself does not follow the hosted-hive daily/weekly cadence: when hub auto-upgrade is enabled and not paused, the hub rolls itself instantly once a newer hive-hub image is published for its branch (the SHA poller logs audit: hub auto-upgrade triggered), independently of any in-flight fleet wave. To keep those rolls from disturbing fleet alerting, the hub persists its alert bookkeeping (observed spoke start times, upgrade marks and each condition's first-seen time) to /data/saas/hub-alert-state.json, and for the first 10 minutes after it (re)starts it does not raise a new crash-loop or offline alert — a condition already firing before the restart keeps firing (#11826).

If a spoke was asked to upgrade to an immutable SHA whose image never appears (for example because a superseded build was cancelled), the visible upgrade attempt no longer stays "queued" indefinitely. After the HIVE_UPGRADE_UNPUBLISHED_TARGET_GRACE grace (default 20m), /api/version marks the request as superseded by the newest published reachable image and shows the substitution reason; once the running pod has already landed at that newer published image, the stale queued state clears as superseded instead of continuing to report the cancelled SHA.

Rolling a hive back to any of the immutable rows above, and proving by digest that the rollback landed, is documented in release-rollback.md.

How a release is actually built

tagged-release.yml does not rebuild the image. docker.yml's own freshness guard already proved, for this exact commit, that the pushed digest's embedded commit hash matches — rebuilding would only reintroduce the risk that guard exists to eliminate. Instead, tagged-release.yml retags the already-published <7-hex-sha> digest as the immutable version tag with docker buildx imagetools create, the same primitive src/scripts/publish-image-tags.sh already uses for the moving tags. The published v1.2.3 image is byte-identical to the <sha> / v4-latest image docker.yml published for that commit.

Concretely, per release:

  1. derive-release-version.sh decides release=true and a version.
  2. Refuse if v<version> already exists as a git tag (idempotency guard — should never trigger in the normal path; see below).
  3. docker buildx imagetools create retags hive, hive-contributor, and hive-hub at :<7-hex-sha> as :v<version>. hive-mx (the mail receiver, src/Dockerfile.mx) is built and published by docker.yml on every release-line push like the others (:<7-hex-sha>, :<branch>-latest, :latest, :candidate), but is not yet retagged as :v<version>, promoted to :stable or pruned: deploy it pinned by tag and digest.
  4. changelog.d/ fragments are compiled into ## Unreleased (src/scripts/compile-changelog.sh — the same compile the decide job ran working-tree-only, now on the release job's fresh checkout), then the whole section is moved into a dated ## YYYY-MM-DD (v<version>) section (the file's own documented convention — see its "How we maintain this file"), a new empty ## Unreleased is left above it, and the consumed fragment files are deleted. 4a. Syft generates an SPDX JSON SBOM for each of the three retagged images (see "Software bill of materials (SBOM)" below) — this happens before the changelog commit, using the version tag written in step 3.
  5. That change is committed (git commit -s, signed off by the release bot). 5a. Before it can reach v5, the commit has to earn the gate check that branch protection requires (see "Satisfying branch protection" below). The commit is pushed to a throwaway release-gate/v<version> branch, docker.yml is dispatched, and the workflow waits for gate to succeed on that exact SHA. It then mirrors the verified result as a SHA-scoped gate: success commit status so a release PR can see it.
  6. The workflow opens a PR from the scratch branch into v5 and merges it through the SHA-keyed merge API as a merge commit, leaving branch protection fully enforced (a direct fast-forward push is tried first when v5 is still at the built SHA). If v5 has moved on meanwhile the merge is simply retried — the base having moved is not a reason to defer. It deletes the scratch branch, then creates and pushes the v<version> tag on the release commit itself (the built SHA plus the changelog), never on the merge commit, so the tag's tree is exactly what the retagged images were built from.
  7. A GitHub Release is created from the tag, with GitHub's auto-generated notes plus an SBOM callout, and the three SBOM files from step 4a attached as release assets. The notes body is the tag's dated CHANGELOG.md section, capped by src/scripts/release-notes-cap.sh at RELEASE_NOTES_MAX_CHARS (120000 bytes by default) before the SBOM/NOTICE trailer is appended: GitHub rejects release bodies over 125000 characters, and the first release on a new line (v6.0.0 carried every fragment since the line diverged, ~877 KB) would otherwise fail this step after the tag and image retags have already landed. When the cap bites, the section is cut at a bullet boundary and ends with … (N more entries) — full notes in CHANGELOG.md, a link to the tag's own section, so the trailer and the asset list always survive.

Satisfying branch protection

v5's only required context is gate (docker.yml). The release commit is created inside tagged-release.yml, so it has no check when it first exists; a direct push to v5 is rejected (GH006: Required status check "gate" is expected, #5026). Retrying does not create the missing evidence, so every attempt fails identically.

The workflow first pushes the commit to release-gate/v<version>, dispatches docker.yml, and waits for its gate check-run on the exact release SHA. That verifies the same code path as an ordinary PR gate, but a workflow_dispatch check-run has no pull-request association: its pull_requests list remains empty even if it is dispatched after the release PR exists. Consequently GitHub's protected-PR rollup omits it and the merge API still reports gate as expected (#5356).

After the check-run succeeds, the workflow posts a gate: success commit status on the same SHA using its GITHUB_TOKEN and statuses: write permission. A commit status is SHA-scoped rather than check-suite/PR-scoped, so it appears in the release PR's required-context rollup. This is a mirror, not a second source of truth: a missing or red docker gate prevents the status from being posted, a failed status POST prevents the PR from opening, and the SHA-keyed merge API still asks GitHub to enforce v5 protection server-side.

Required PR contexts that are expensive and path-sensitive still have to report on every head SHA. The release-line workflows therefore keep their pull_request triggers unfiltered for required contexts, broaden CI-sensitive push filters to .github/workflows/** and .github/scripts/**, and decide inside the job whether to run the real lane or report a successful out-of-scope result. Workflow-only PRs run the real CI because they can change the gate itself; docs-only or other exempt diffs get a same-named success/skipped result instead of leaving branch protection stuck on an "expected" check.

Getting docker.yml to actually run on the scratch branch (#5072): docker.yml's push trigger is branches: ["**"] (minus bot branches — see .github/release-lines.yml's unpinned entry for it), which on paper covers release-gate/* too — but the scratch push uses this job's default GITHUB_TOKEN, and GitHub deliberately does not start other workflow runs from a GITHUB_TOKEN-authenticated push (recursive-workflow prevention). The push trigger silently never fires, no gate check ever attaches to the commit, and the wait loop times out — every release run failed this way until #5072. docker.yml also has a workflow_dispatch trigger, which a GITHUB_TOKEN can start via the API (gh workflow run docker.yml --ref release-gate/v<version>), and that run's check-runs attach to the scratch branch's head SHA exactly as a push-triggered run's would — so this step dispatches it explicitly right after the scratch push, rather than relying on the push trigger.

workflow_dispatch on docker.yml normally forces a GHCR push regardless of branch (so a throwaway branch can be published for a hive on demand) — which would mean every release pushes a real, one-off release-gate/v<version> image and moving tag to GHCR purely to obtain a status check that only needs the gate job (a few seconds) to run. docker.yml's gate job carries a release-gate/* exception so that never happens, on any trigger: the scratch branch name is deliberately not in docker.yml's LONG_LIVED set (v4 v5 mk dd) and the exception forces push=false for it unconditionally, so this detour never pushes a GHCR image or moves a channel tag; gate runs regardless of push policy, which is all this needs. The scratch branch is deleted by the merge step's trap ... EXIT once that step starts, whether the PR merges or fails. A failure during the preceding gate-earning step leaves the branch in place for diagnosis.

This preserves branch protection exactly as configured — no bypass, no weakened check, no enforce_admins change, and no force push. The workflow earns the real docker gate on the scratch branch, mirrors that exact-SHA verdict into the representation the release PR can consume, and lets the protected merge endpoint make the final decision.

Building the merged release commit: the release_sha dispatch (#6380) and its ancestry gate (#6419)

The merge in step 6 is performed with the workflow's own GITHUB_TOKEN, and GitHub deliberately does not start other workflow runs from a GITHUB_TOKEN-authenticated push (the same recursive-workflow prevention described for the scratch branch above). So the release commit landing on v5 fires no push-triggered docker.yml build — without intervention the release commit would never get its own images, and the moving tags would stay pointed at the pre-release tree. tagged-release.yml therefore dispatches docker.yml explicitly, immediately after the merge succeeds (#6380):

gh workflow run docker.yml --ref v5 -f release_sha=<sha>

passing the merge API's exact returned SHA rather than letting the dispatched run resolve v5's tip, because another PR can advance v5 between the merge and the build starting. That is what docker.yml's release_sha workflow_dispatch input exists for; left empty (an ordinary manual branch build), the run builds the dispatched ref's tip as usual.

The receiving end fails closed (#6419, v4.23.0). Until then, docker.yml's gate job validated release_sha only as well-formed 40-hex — and well-formed hex is not "in this branch's history." Any principal with actions: write could dispatch release_sha=<any commit object in the repo> — including an unreviewed PR head — and every downstream job would build and publish it under the branch's moving tags (<branch>-latest, candidate, …), laundered through the normal pipeline with legitimate provenance labels. tagged-release.yml, the only intended caller, already ran a git merge-base --is-ancestor check before tagging, but the gate job re-verified nothing on the receiving end. When (and only when) a release_sha is supplied, the gate job now checks out the dispatched ref with full history and runs src/scripts/check-release-sha-ancestry.sh, which refuses — exit 1, build never starts — unless the SHA is a full 40-char lowercase hex string, resolves to a real commit object, and is an ancestor of the dispatched ref. The ordinary push/PR path (the overwhelming majority of runs) pays no extra fetch. The check lives in a standalone script rather than an inline run: block so it is testable against fixture repos (src/scripts/test-check-release-sha-ancestry.sh) instead of only being provable inside a live Actions run.

The dispatched build completing does fire a workflow_run event back at tagged-release.yml, but its decide job deliberately ignores workflow_dispatch-triggered builds (see "Idempotency and concurrency" below), so the release pipeline never chases its own tail.

Software bill of materials (SBOM)

Every tagged release ships a downloadable SBOM per image — hive, hive-contributor, hive-hub — attached to the GitHub Release as hive-v<version>-sbom.spdx.json, hive-contributor-v<version>-sbom.spdx.json, and hive-hub-v<version>-sbom.spdx.json. Format is SPDX JSON, generated by Syft (anchore/sbom-action), scanning the already-published, just- retagged v<version> image reference on GHCR — not the source tree. A source-tree scan would report what go.mod/package.json ask for; scanning the built image reports what the shipped filesystem actually contains — the apk-installed OS packages, the from-source tmux/Node layers, and the exact resolved Go module versions — which is the more faithful record for anyone consuming a specific release's security posture.

Coverage limitation, stated plainly: hive and hive-hub are multi-arch (linux/amd64, linux/arm64); the SBOM step scans the linux/amd64 manifest only, not linux/arm64 separately. This is a documented limitation, not a silent gap: a Go binary's cross-compiled machine code differs by architecture but the package versions that produced it — Go module versions, apk/npm package versions in the same Dockerfile layers — are identical on both, and an SBOM describes packages and versions, not compiled bytes. One architecture's manifest is therefore representative of both, and the GitHub Release notes say so explicitly rather than implying full multi-arch coverage.

Why this is a release artifact, not an in-image attestation

docker.yml sets provenance: false and sbom: false on every docker/build-push-action step, on purpose, and .github/workflows/image-attestation-guard.yml + src/scripts/check-no-image-attestations.sh guard those four sites in CI so a well-meaning revert fails loudly instead of shipping. The reason (#3760, documented at length directly above each flag in docker.yml): build-push-action attaches provenance/SBOM attestations by default, and an attestation can only be carried by an OCI image index — so turning it on changes the published per-arch digest from a plain image manifest to application/vnd.oci.image.index.v1+json. That index form is exactly what let a COPY --from=builder layer ship an overlayfs metacopy redirect for /usr/local/bin/hive, which containerd/k3s and rootless podman present as non-executable at the image path until copy-up — every hive pulling such an image crash-looped at boot on a bare EPERM at execve. The image manifest format is therefore a hard constraint, not a style preference: it must stay a plain manifest.

The release SBOM generated here never touches that constraint. It runs after docker.yml has already published the plain-manifest image (tagged-release.yml retags, never rebuilds — see above), scans the published digest from the outside with an independent tool, and writes an ordinary JSON file that is uploaded to the GitHub Release. Nothing about generating it adds an attestation to the GHCR image, changes its media type, or touches the manifest docker.yml published. If a future change moves SBOM generation back into docker.yml's build-push-action steps (e.g. by flipping sbom: true), it reopens #3760 — that is exactly what the guard workflow exists to catch.

Third-party notices (NOTICE)

The repo root carries a generated NOTICE file: one entry per Go module dependency compiled into hive, hive-hub, and hive-contributor, with module path, resolved version, license identifier, and — once CI has produced the authoritative version — the full license text where the license requires reproduction (Apache-2.0 §4(d), MIT, and BSD all do). This exists because a CNCF General Technical Review asks how the project ensures third-party code carries correct and complete attribution; go.sum pins dependency versions but was never, by itself, an assembled attribution document.

How it is generated. src/scripts/generate-notice.sh walks the resolved module graph (not just go.mod's direct requires) using google/go-licenses, pinned to an exact tagged version and installed via go install — the same pattern go-security-analysis.yml already uses for govulncheck and gosec, for the same reason: a supply chain one hop shorter than depending on a marketplace action, and a version that only changes when a maintainer deliberately bumps it. The script's own header explains why go-licenses was chosen over a hand-rolled go list -m -json all walk.

How freshness is enforced. The notice-drift job in go-security-analysis.yml regenerates NOTICE on every push and pull request touching src/go.mod, src/go.sum, or the generator script itself (plus weekly, since an upstream dependency's license text can change without a version bump), and fails the build if the committed file differs from a fresh run, ignoring the Source: lines (go-licenses resolves them with a remote lookup that can transiently yield Unknown, #11497). A generated file that can silently go stale is worse than no file at all — it would make a false completeness claim the moment a dependency changed. There is deliberately no special-case to tolerate an out-of-date NOTICE: the fix is always "run the script, commit the result."

Current state of the committed file. NOTICE is the authoritative, go-licenses-generated output from the resolved module graph. The generator uses go-licenses report rather than save: save refuses to emit anything when the graph contains a license class the tool considers incompatible, while an attribution inventory must identify every dependency, including a restrictively licensed one. Inclusion in NOTICE records what ships; it is not an approval or compatibility decision. License-acceptance policy belongs in a separate gate so it cannot make this inventory incomplete.

What NOTICE does NOT cover. Go module dependencies only. It does not cover:

  • Base container image OS packages (the apk-installed package set) — those are covered by the per-image SBOMs above, which scan the built filesystem rather than the source tree.
  • The Node.js and tmux layers built from source in src/Dockerfile / src/Dockerfile.hub — also covered by the SBOMs, not NOTICE.
  • Anything in dashboard/ or other non-Go parts of the repo that may carry their own dependency manifests (npm, etc.) — out of scope for this file; a JS/TS equivalent, if wanted, is a separate follow-up.

NOTICE and the per-image SBOMs are therefore complementary, not redundant: NOTICE gives license text for Go dependencies (what the SBOM format does not carry), and the SBOM gives full package inventory (OS + language runtime layers) that NOTICE does not attempt.

Shipped in releases. tagged-release.yml copies the repo-root NOTICE (already kept fresh by notice-drift at every commit that changes dependencies) to hive-v<version>-NOTICE and attaches it to the GitHub Release alongside the three SBOM files, using the same gh release create asset-upload call.

Idempotency and concurrency

  • The release commit's own build cannot re-trigger a release. The GITHUB_TOKEN-authenticated merge fires no push event, so the release commit's images come from the explicit release_sha dispatch (#6380 — see above), and tagged-release.yml's decide job deliberately filters out workflow_dispatch-triggered docker.yml runs, so that build's workflow_run event is a no-op. Even on a path that does re-evaluate the released tip (the hourly #5318 backstop), step 5 emptied Unreleased, so derive-release-version.sh returns release=false. It never chases its own tail — belt and suspenders.
  • concurrency: { group: tagged-release-v5, cancel-in-progress: false } serializes overlapping runs so two merges landing close together queue rather than race two tags for two different commits.
  • A re-run after a partial failure (for example, the images got retagged but the push failed) is safe: imagetools create is itself idempotent per tag, and the "refuse to reuse an existing tag" step turns any genuine double-run attempt into a loud failure instead of a silent duplicate.
  • The version a running binary reports can never disagree with its tag, because the version is never a source-committed string to fall out of sync — see below.

The version constant

cmd/hive/main.go carries one var version = "0.0.0-dev", overridable at build time via -ldflags -X main.version=..., exactly like the existing gitHash/gitShort/gitBranch build-time vars. src/Dockerfile and src/Dockerfile.hub both accept an optional VERSION build-arg — but they no longer leave it empty on an ordinary build. When no VERSION is passed, each Dockerfile derives one from git describe --tags --always against the /repo/.git it copies in, so an ordinary docker.yml build self-stamps a real value: 4.34.0 when built exactly at tag v4.34.0, or 4.34.0-7-g43a51078 a few commits ahead (nearest tag + commits-ahead + short commit). A leading v is stripped by main.go's reportedVersion() so the three consumers (--version, hub heartbeats, dashboard registration) always see digit-leading semver. docker.yml's image-build jobs check out with fetch-depth: 0 and fetch-tags: true so the tag history git describe needs is present; a build with no ldflag at all (a bare local go build) still falls back to 0.0.0-dev, never an empty string.

For semver releases, tagged-release.yml dispatches docker.yml with the exact merged release SHA, and — only when v5 was still at the built SHA, so the merge adds nothing but the changelog — the exact tag (VERSION=v5.x.y). That keeps the retag model while making the binary self-report the release it is published as instead of the previous nearest tag. When the release landed as a merge commit onto a tip that had moved on, the merge commit also carries newer work, so VERSION is left empty and git describe reports v5.x.y-N-gSHA, which is accurate. Branch and manual non-release builds leave VERSION empty likewise.

What still blocks cutting a real release

The --version self-report gap is now closed (see "The version constant" above): release docker.yml builds stamp the binary with the release tag, so a release image published as v5.35.2 self-reports 5.35.2; branch builds report 5.35.1-7-gSHA-style git describe output instead of the old static 0.0.0-dev. What remains is a maintainer product decision, not a wiring gap:

  • The running binary's --version now varies per build. Release images report the tag tagged-release.yml passed to docker.yml; non-release branch images report the git describe string for the built commit. That is faithful, not a lie: gitShort/ gitBranch remain exact, and the image tag is still authoritative for a named release. The release tag is injected during the dispatched release build; the later tag/manifest publication still reuses that tested digest rather than rebuilding an untested one.
  • No starting version has been chosen. With zero existing tags, the first automated release computes its base as 0.0.0 and bumps from there (so the first ## Added entry ships as v0.1.0, not v1.0.0). If the project wants its first tag to read v1.0.0, a maintainer needs to push that tag by hand once, after which every future release bumps from it normally — this workflow deliberately never invents a major version on its own authority.
  • This PR does not create any tag. No v*.*.* tag or GitHub Release exists yet as of this PR; the very next content-carrying merge to v5 (after this PR itself merges, assuming its own CHANGELOG entry survives under ## Unreleased) is what would cut the first one.