Skip to content

Architecture

Release code

How the release train turns a main commit into pinned deployable artifacts.

On this page

Release behavior lives in code too. app/release is a Go CLI, and .github/workflows/release.yml runs its stages in separate jobs. The admin console can start the workflow; it does not become a second release implementation.

Inputs and state

The CLI accepts release, hotfix, bump, rollback and reapply. Its flags include the version, target main SHA, PRs to merge, selected services and a changelog JSON path. -stage runs a single stage. -state selects the persisted run file; an existing file is resumed instead of seeded again.

internal/domain/rpc/deploy defines the shared run contract. app/release/internal/train drives the run. Ports isolate GitHub, registry and clock behavior from orchestration, so the train and stage tests can use fakes.

flowchart LR
    Request["Release request"] --> Preflight["Validate inputs and ancestry"]
    Preflight --> Build["Applicable merge, tag and build stages"]
    Build --> Digests["Resolve image digests"]
    Digests --> Pins["Merge artifact pins into main"]
    Pins --> Promote["Fast-forward deploy to main commit"]
    Promote --> Flux["Flux reconciles tracked resources"]

The exact stage selection depends on the run kind. Read app/release/internal/stages/github and the workflow before changing that selection.

The branch contract

main owns artifact pin changes. deploy points to a main commit and advances by fast-forward. It does not receive a separate promotion commit. Rollback makes a new pin change on main and promotes that commit; it does not rewind deploy history. Reapply must also satisfy the ancestry checks.

That contract lets the deployed state be traced back to reviewed source and pins. A direct edit to the deploy branch breaks the release model even if the files look right.

Work on the train

Start with app/release/main.go, the train tests and the stage tests. Use fakes while changing orchestration. A real CLI run can merge PRs, tag, publish images and move a branch, so it is not a local smoke test.

go test ./app/release/...

Deployment topology and provider credentials are separate from the release state machine. This page documents the code contract rather than a particular cluster layout.

Source: release CLI, workflow.

Failure, recovery and validation

The train records each attempt as running, succeeded, skipped or failed. An error marks the stage and run failed; the driver stops. On a resumed run, succeeded and skipped stages are not due again. Before running a stage, its Done check can recognize work already completed. A state file records orchestration progress; inspect the external GitHub and registry state as well before retrying an interrupted operation.

go test ./app/release/... exercises the train and stage tests without making a real release. The workflow and stage implementations remain authoritative for which steps run for each request. A completed promotion advances Git state; reconciliation by Flux is a separate outcome and should be verified separately.