The Build & Release Pipeline
This page explains how an InterGenOS release goes from unvetted integration work to a stable image you can daily-drive — what a candidate is, what promotion means, and why a full from-scratch build on real hardware is the proving ground. It is written for anyone who wants to understand how the system is built; it describes intent and the shape of the process, not internal commands or machine-specific detail.
Status (1.0 development line). The naming and the flow below are the release model the project builds against today. Concrete candidate numbers advance as the line progresses; the structure — candidate, promotion gate, stable golden — is stable.
A clean build is not a finished release
InterGenOS is built entirely from source, from pinned, checksum-verified inputs, with a deterministic build. But a build in which every package compiled is not the same thing as a build that is known-good. The expensive defects of a from-source distribution are not compile errors — they are the class of problem that compiles fine, packages fine, and only shows up when the image is actually installed and booted on real hardware: a service that writes state a strict sandbox forbids, a directory left out of a package’s file list so a registry initializes empty, a hardware-detection heuristic that picks a path a given GPU cannot drive.
None of those is caught by “everything compiled.” Every one of them is caught by installing the image and booting it on real hardware. That is the single idea the whole pipeline is built around, and it is why a candidate is never trusted on the strength of a clean build alone.
A candidate: honest provenance
While work is still being integrated and has not yet earned that trust, the
artifacts it produces are labelled as candidates, with a -DEV suffix that states
their provenance honestly. A build generated off the integration line can only
attest to integration-line source, so its artifacts wear that label until they are
proven — it is a truthful description, not a placeholder.
One integration build produces two distinct objects, and it helps to keep their roles straight:
- A Release Candidate image (for example
RC001-DEV) — the ISO you install and boot-test. Being “vetted for daily use” is a property this image earns by passing its own install-and-boot validation. - A candidate build substrate (a from-scratch dev candidate) — a large, fully-built environment captured from the same build, kept so that further work can be built on top of it without recompiling everything from scratch. It is unvetted build material, not something you install.
Promotion is the event that earns the name
Promotion is what turns a candidate into a release. A from-scratch,
validation-inclusive build that compiles cleanly and whose Release Candidate
image installs, boots, and validates on real hardware is promoted from the
integration line to the stable line. In the same move it drops the candidate
marking — both the C and the -DEV fall away — and mints a stable golden
substrate: the “built a ton, it works, daily-drive” image
that subsequent, more targeted package work is built against.
A stable golden never carries a -DEV suffix. Once promoted it certifies
stable-line source, so a candidate marking on it would contradict itself. The
candidate labels live only during a candidate’s pre-promotion life.
The whole flow, from in-progress work to a trusted release, is a single loop — a candidate is built, put through the proving ground, and either sent back for a fix or promoted:
flowchart TD
A["Integration work<br/>the in-progress line of changes"] --> B["Build a release candidate<br/>a complete test image — not yet trusted<br/><i>named RC…-DEV while unproven</i>"]
B --> C{"<b><u>THE PROVING GROUND</u></b><br/>Builds cleanly from scratch,<br/>then installs and boots on<br/>real hardware?"}
C -->|" No — a genuine build defect "| D["Fix the cause in the source"]
D --> A
C -->|" Yes — proven "| E["Promote to a stable release<br/><i>the -DEV label is dropped</i>"]
E --> F["The trusted baseline<br/>future targeted updates build on top of it<br/><i>named GB…</i>"]
classDef gate fill:#fde68a,stroke:#b45309,color:#111827;
classDef good fill:#bbf7d0,stroke:#15803d,color:#111827;
class C gate
class E good
class F good
Read it as a story: work in progress becomes a candidate image; the candidate only earns the “stable” name by building cleanly from nothing and then installing and booting on real hardware; anything that fails sends the fix back to the source and the loop repeats; what comes out the far end is the trusted baseline the next round of work builds on.
Why from-scratch is the proving ground
The promotion build is deliberately a full, from-scratch run rather than a quick rebuild of what changed. A targeted rebuild is the right tool for iterating during development — it is fast because it only recompiles what actually changed — but it inherits an already-built environment, so it cannot re-prove that the whole distribution still assembles cleanly from nothing. The from-scratch promotion build does exactly that: it rebuilds every package from pinned source, then the resulting image is installed and booted on real hardware before the release name is granted.
Not every halt disqualifies a candidate. A build can stop for reasons that are about the build scaffolding rather than a defect in the release itself; those are fixed and the build resumes without resetting the candidate’s standing. What blocks promotion is a genuine build defect, or an image that does not install and boot cleanly. When something does fail, the cause is fixed in the source tree and the candidate iterates — never worked around, never masked.
Related
- Building Packages from Source — how an individual package is compiled from pinned source.
- The Transparent Package Manager — how built packages are installed and verified.
- Reproducibility & Verification — how a build’s inputs and outputs are made checkable.