docs/release.md had grown into one page that mixed the release model, the CI pipeline, changelogs, signatures, nightlies and the fires seen at release time. A reader looking for one of them read all of it, and an edit to one part reflowed the rest. It now indexes one page per topic under docs/release/. The pages already describe how fixes reach a release line through the backport batch, which the following commits add. Workflows, scripts and tests that named docs/release.md now point at the page that holds the text they mean. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
9.3 KiB
Regular Releases
A regular release vX.Y.0 is promoted from a release-candidate that already passed e2e — never tagged by hand and never rebuilt. The bytes shipped as vX.Y.0 are the exact vX.Y.0-rc.N images, retagged by digest. We'll use v1.2.0 as an example.
gitGraph
commit id: "feature"
commit id: "feature 2"
commit id: "feature 3" tag: "v1.2.0-rc.1"
A regular release sequence runs as follows:
-
Cut the first release candidate (
v1.2.0-rc.1) from the last good commit onmain: run theCut Pre-release Tagworkflow (manual dispatch frommain) with the tag. It tagsmain's HEAD as the CI app, then createsrelease-1.2at that commit, freezing the line;tags.yamlthen builds the rc images, publishes the rc prerelease, pushes the digest-vendoredrelease-1.2.0-rc.Nstaging branch, and runs its mandatoryrc-e2ejob by callinge2e-tag.yamlagainst that published tag. -
Watch the rc's mandatory full E2E and wait for it to pass, then complete the other checks in Pre-release verification checklist. If the latest
tags.yamlrun cannot provide a greenrc-e2e, a successful manual dispatch ofe2e-tag.yamlfor the same tag is equivalent gate evidence.mainis already open for the next minor, so anything landing there is not in this release until it reachesrelease-1.2: a fix merged intomaingets there through the backport batch, which runs forrelease-1.2from the freeze on, and a fix with no counterpart onmainthrough a maintainer's pull request againstrelease-1.2. A later rc is cut by dispatching the workflow fromrelease-1.2, and only once./backport-batch check --line release-1.2 --cutexits 0: merge the open batch pull request first, so that the rc carries every fix the policy takes. Optional: once the notes are worth reviewing, press theGenerate RC Changelogbutton (changelog-rc.yaml) to generatedocs/changelogs/v1.2.0.mdnow and bank it on therelease-1.2.0-rc.Nstaging branch — so there is time to review and hand-edit it before promotion. Skipping the button changes nothing; promotion generates the changelog itself.gitGraph commit id: "feature" commit id: "feature 2" commit id: "feature 3" tag: "v1.2.0-rc.1" branch release-1.2 checkout main commit id: "feature 4 (next minor)" checkout release-1.2 commit id: "backported fix" tag: "v1.2.0-rc.2" -
Once the checks are green, run the
promote-rc.yamlworkflow (manual dispatch frommain, the only branch it is dispatched from, whichever line the rc belongs to) with that rc tag. Itsparsejob verifies E2E before any staging: it accepts a successfulrc-e2ejob in the latesttags.yamlpush run for the tag, or any retained successful manuale2e-tag.yamlrun whose expanded E2E job name targets the tag. The emergencyskip_e2e_gateinput bypasses this check, logs a loud warning, and marks the promote PR with ⚠️. Before its first registry write, promotion also proves that the selectedmainorrelease-X.Ytarget already contains the candidate-aware PR gate, finalizer and trusted verifier. A maintenance branch that lacks them gets them before its next patch is promoted, through the batch withbackport/includeon the pull request that brought them tomain, or through a maintainer's pull request against the line. Promotion creates no stable name before merge: dispatch does write to the registry — it publishes onepromotion-*packages candidate, and that tag is real and publicly listable — but it creates novX.Y.Ztag, moves nolatest, and publishes no stable installer, so nothing a consumer resolves changes until the PR merges. It:- Rewrites the rc version substring to
1.2.0and commits that exact tree, serializes itspackages/directory under a run-specific temporary OCI tag, then adds a second commit pinning the candidate's immutable digest in the installer before pushingrelease-1.2.0. Container digests remain exactly the rc's; the two commits give the OCI revision an honest source SHA without pretending the artifact can contain its own digest. - Drafts the
v1.2.0release and uploads the (restamped) assets. - Generates
docs/changelogs/v1.2.0.md(in a parallel job, detached at the rc tag) — or, if you pressed the rc-timeGenerate RC Changelogbutton, copies the file already banked on therelease-1.2.0-rc.Nstaging branch instead of regenerating — and commits it onto therelease-1.2.0branch, so the changelog is reviewed as part of the promotion and finalize can publish the release with it already in place. Non-blocking: if generation fails the PR still opens, carrying a ⚠️ line that says the changelog is missing. - Opens the
cozystack/website"update managed apps reference" PR (update-docs-v1.2.0branch), generating the docs from therelease-1.2.0staging branch viaFETCH_REF. Non-blocking, and do not merge that PR untilv1.2.0is published — merging early breaks the live site's version routing (see Phase 3). - Opens the
chore(release): promote v1.2.0-rc.N -> v1.2.0PR intorelease-1.2, labelledreleaseonly. The PR body records whether E2E was verified or bypassed, plus ✅/⚠️ changelog and website-docs lines. E2E does not run on this promote PR by default because the immutable rc already passed the mandatory full suite; a maintainer may addfull-e2eto run it again. The stable retag itself is deferred to the merge (step 5), so an abandoned promotion leaves no stable-named images and cannot wedge a re-promotion; retention protects the temporary candidate for as long as this release PR remains open, then may remove it after 30 days.
The PR targets the maintenance branch, not
main:promote-rc.yamlprefersrelease-X.Ywhenever it exists, and since the rc freeze it always does. The digest-vendoredPrepare releasecommit therefore stays on the release line instead of landing onmain.gitGraph commit id: "feature 3" tag: "v1.2.0-rc.1" branch release-1.2 checkout release-1.2 commit id: "backported fix" tag: "v1.2.0-rc.2" branch release-1.2.0 checkout release-1.2.0 commit id: "Prepare release v1.2.0" commit id: "Pin promoted packages artifact" checkout release-1.2 merge release-1.2.0 id: "Pull Request" - Rewrites the rc version substring to
-
Maintainer reviews the PR and the draft release against the Phase 4 checklist: confirm the E2E-verification line is ✅ (or explicitly accept its ⚠️ bypass), the changelog line is ✅, and note the website-docs line — the
cozystack/websitedocs PR that promotion parked, which stays unmerged for now. E2E does not run on this promote PR by default. Then merge — do not squash-merge, the stable tag must attach to a real merge commit. GitHub removes the merged branchrelease-1.2.0(the repo has auto-delete-on-merge enabled). -
CI workflow triggers on merge (this is where every consumer-visible or write-once side effect happens, after the rc E2E gate and PR review):
- Pulls the pinned packages candidate by digest and verifies that it matches the merged
packages/tree apart from the artifact's impossible self-reference, carries no rc image tags, and preserves the original rc artifact's containerrepo@digestset. - Creates the tag
v1.2.0at the newly created merge commit — write-once. The tag is published here for the first time, never moved. - Cuts the write-once
api/apps/v1alpha1/v1.2.0Go-module tag at the same commit. - Ensures the
release-1.2maintenance branch exists at the tag commit. Since the rc freeze created it, this is normally a no-op fast-forward: the merge commit is already its tip. - Publishes the release page (
draft→latest), usingdocs/changelogs/v1.2.0.mdfrom the merge commit as the release body. - Retags the verified packages candidate and rc container images by digest to
v1.2.0(and:latestonly whenv1.2.0is the newest published stable), and publishes the stablecozy-installerchart — no container rebuild.
- Pulls the pinned packages candidate by digest and verifies that it matches the merged
-
Once the release is published, merge the parked
cozystack/websitedocs PR (opened back at promote time, step 3.iv) so the live site's version routing flips tov1.2.0— its versioned docs andopenapi.jsonare on GitHub now. The maintainer can then announce the release to the community.
gitGraph
commit id: "feature 2"
commit id: "feature 3" tag: "v1.2.0-rc.1"
branch release-1.2
checkout main
commit id: "feature 4 (next minor)"
checkout release-1.2
commit id: "backported fix" tag: "v1.2.0-rc.2"
branch release-1.2.0
checkout release-1.2.0
commit id: "Prepare release v1.2.0"
checkout release-1.2
merge release-1.2.0 id: "Release v1.2.0" tag: "v1.2.0"
Note that main never receives the release commit. It forked away at the freeze and carries the next minor's work.