ADR 0031: one build and release contract for Core and an organization
Status: accepted (2026-11-12)
Context
Core publishes reference workstations from this repository. An organization publishes its own workstation from a repository that pins Core resources and adds organization profiles. The two pipelines answer the same questions (what was built, what booted, what was scanned, what a person approved) with different stages, names and failure rules.
Measured on 2026-11-12:
- Core scans inside
image-publish, before anything is pushed. - The organization publishes a boot-checked commit and an
:edgetag before the scan, then the scan moves:candidateand:latest. - Core builds the installer in a reusable
installer-buildworkflow, called after the image publish. The organization builds the ISO inside the image job, so an ISO failure also stops the scan and the image channel. - The workflow names carry an organization prefix in one repository and not in the other, and the tag set differs by one tag.
Two pipelines mean two mental models, two review checklists and two ways for a release to fail. The user asked for one contract: same process, same names, same tag vocabulary.
Decision
Both repositories use five stages, with these names and this order.
| Stage | Workflow | What it does | Moves |
|---|---|---|---|
| 1 | image-publish[-<platform>].yml | Build; declared and installed SBOMs; compare; boot, session and first-boot checks; push the immutable commit; sign it | :edge |
| 2 | image-scan[-<platform>].yml | Grype and the reviewed exceptions against the published digest | :candidate, :latest |
| 3 | promotion.yml | Verify signature, evidence and approval record; promotion-weekly.yml calls it once per flavor | :stable |
| 4 | installer-build.yml | Build the ISO from the published digest and sign it; installer-weekly.yml calls it from :stable, a manual publish calls it with the image | :candidate, :stable |
| 5 | installer-test.yml | Install unattended in QEMU, on demand | none |
- Cadence. The contract fixes the stages and the meaning of each tag, not how often a pipeline runs them. Core builds and promotes weekly; an organization may build daily and promote weekly, which is what DayTwo does.
- Names. Workflows are
<stage>[-<platform>].yml, without an organization prefix. Jobs areresolve,build,verify,scan,publish,approve,installer,stableandiso. Two wrappers carry the cadence:promotion-weekly.ymlandinstaller-weekly.yml. Repository names stay<project>-<variant>-<platform>. - Steps. The boot checks are named “Boot check”, “Session check” and “First-boot check”; the scan step is “Scan (Grype)”; the signing step is “Publish, sign and attest”; the installer steps are “Build the installer ISO” and “Publish and sign the installer”.
- Tags.
:edgeis image only and means “the build boot-checked and signed this digest, before the scan”.:latestmeans “the scan passed”.:stablemeans “the evidence and the approval were verified”; it is promoted weekly from:candidate, and the installer is built weekly from it, so the installer's:latesttrails the image's.:candidateis the source a promotion checks. - Failure rules.
- A failed scan leaves
:latestand:stablewhere they were;:edgedoes not move back. - A failed ISO does not stop the image: the image keeps its channels and the
installer waits at
:candidate. - A failed promotion leaves
:latestmoved and:stablebehind. installer-testnever gates publication; it is a separate signal.
- A failed scan leaves
- Publication. Core publishes the platforms it owns and never RHEL. An organization publishes its own images, and its RHEL artifacts stay private. This contract changes the stages, not who may publish what.
Consequences
Core must split the scan out of image-publish, publish the commit before the
scan and add :edge. That changes what exists before the gate: an unscanned
commit and :edge become visible. The channels that a machine follows do not
change: :latest and :stable still require the scan and the promotion.
An organization must extract the ISO from its image job into installer-build,
rename the workflows, and let a failed ISO stop only the installer. Its scan
matches stage 2; its promotion is called weekly from :candidate by
promotion-weekly.yml, and installer-weekly.yml builds the ISO from :stable.
Neither repository tests the published ISO’s install path today. Core’s
installer-test builds a test-only ISO; an organization has no installer test.
Until stage 5 exercises the published ISO, both advertise an installer whose
install path is unverified. That gap is named here rather than hidden.
The migration is staged: the names and the ISO split first, the cadence split next (daily build, weekly promotion and ISO), then the Core scan split, and the installer smoke test last. Existing release records and tags stay readable; no digest is rebuilt to satisfy the contract.