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.
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.ytags from its own branch.tagged-release.ymlserves the branch it was started from (RELEASE_LINE: ${{ github.ref_name }}— the default branch forworkflow_run/schedule, the chosen ref forworkflow_dispatch) and refuses unless that branch is underrelease_lines.derive-release-version.shbases the next number on the line's own latestvN.*tag only, and the first tag on a line is alwaysvN.0.0regardless of the inferred bump — the human chose the major when they cut the line, sov6's first release isv6.0.0. Av4.*tag never seeds av5number, 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 strayv4.73.3fromv5on 2026-09-21 (deleted; see #7721). v5cutsv5.x.ytags and, as the default branch, is the only line that receivesworkflow_runandscheduleevents directly.v6cutsv6.x.ytags. GitHub deliversworkflow_runonly to the default branch's copy of the workflow, so thev5copy carries arelayjob: whendocker.ymlcompletes a push build on another declared release line, it dispatchestagged-release.yml --ref <line>, and that line's own copy takes the backstop path (resolve the tip, require published images, derive, release) under its owntagged-release-<line>concurrency group. The hourly schedule backstop stays default-branch only; av6build that was cancelled is picked up by its next completed build or by a manualgh workflow run tagged-release.yml --ref v6.v4cutsv4.x.ytags for the security and critical fixes it still accepts under the freeze (#6346). Its copy oftagged-release.ymlis pinned tov4and labels its release PRv4-freeze-exemptso the requiredfreeze-gatecheck lets the automated release commit land.- Channels are independent of tags and did not move with the
v6cut:stable/candidate/latestfollow v5 (stableby digest viapromote-stable.yml, which only ever runs from the default branch),edgeandv6-latestfollow v6, and av6.x.ytag 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.
.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:### Securitypresent → major- else
### Addedpresent → minor - else (
### Changed/### Fixed/### Deprecatedonly) → patch
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.
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>.mdfragment in your PR (asCONTRIBUTING.mdasks, 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; seechangelog.d/README.md. - The filename's category prefix picks the subsection your entry is compiled
into (
added-→### Added, and so on forchanged/deprecated/fixed/security), and the subsections drive the bump exactly as they always have. Existing## Unreleasedentries 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.mdedit), it contributes to whatever release fires next but does not by itself trigger one — and ifUnreleasedandchangelog.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.
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.
| 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.
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:
derive-release-version.shdecidesrelease=trueand a version.- Refuse if
v<version>already exists as a git tag (idempotency guard — should never trigger in the normal path; see below). docker buildx imagetools createretagshive,hive-contributor, andhive-hubat:<7-hex-sha>as:v<version>.hive-mx(the mail receiver,src/Dockerfile.mx) is built and published bydocker.ymlon every release-line push like the others (:<7-hex-sha>,:<branch>-latest,:latest,:candidate), but is not yet retagged as:v<version>, promoted to:stableor pruned: deploy it pinned by tag and digest.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## Unreleasedis 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.- That change is committed (
git commit -s, signed off by the release bot). 5a. Before it can reachv5, the commit has to earn thegatecheck that branch protection requires (see "Satisfying branch protection" below). The commit is pushed to a throwawayrelease-gate/v<version>branch,docker.ymlis dispatched, and the workflow waits forgateto succeed on that exact SHA. It then mirrors the verified result as a SHA-scopedgate: successcommit status so a release PR can see it. - The workflow opens a PR from the scratch branch into
v5and 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 whenv5is still at the built SHA). Ifv5has 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 thev<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. - 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.mdsection, capped bysrc/scripts/release-notes-cap.shatRELEASE_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.
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.
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.
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.
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.
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
tmuxlayers built from source insrc/Dockerfile/src/Dockerfile.hub— also covered by the SBOMs, notNOTICE. - 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.
- The release commit's own build cannot re-trigger a release. The
GITHUB_TOKEN-authenticated merge fires nopushevent, so the release commit's images come from the explicitrelease_shadispatch (#6380 — see above), andtagged-release.yml'sdecidejob deliberately filters outworkflow_dispatch-triggereddocker.ymlruns, so that build'sworkflow_runevent is a no-op. Even on a path that does re-evaluate the released tip (the hourly #5318 backstop), step 5 emptiedUnreleased, soderive-release-version.shreturnsrelease=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 createis 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.
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.
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
--versionnow varies per build. Release images report the tagtagged-release.ymlpassed todocker.yml; non-release branch images report thegit describestring for the built commit. That is faithful, not a lie:gitShort/gitBranchremain 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.0and bumps from there (so the first## Addedentry ships asv0.1.0, notv1.0.0). If the project wants its first tag to readv1.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 tov5(after this PR itself merges, assuming its own CHANGELOG entry survives under## Unreleased) is what would cut the first one.