Design

A high-level tour of what StageFreight actually does when a pipeline runs, and the ideas behind it. Read this to build a mental model; drop into Configuration when you want to drive a specific piece.

The pipeline, phase by phase

A run moves through five load-bearing phases. The exact graph depends on lifecycle.mode, but the canonical lifecycle is:

audition → perform → review → publish → narrate

• Audition — the pre-flight gate that runs before anything is built: lint (content, freshness, secret, and hygiene checks), and in GitOps mode the Kustomize/manifest validation.
• Perform — produce artifacts in containers: images, binaries, kind: command outputs (docs).
• Review — inspect and approve produced artifacts before anything is published.
• Publish — push images, cut releases, deploy pages, run retention.
• Narrate — compose repo-facing content (badges, includes) and commit it.

The authoritative phase sequence and how each phase gates the next live in Pipeline flow.

Deep dives

The notes below explain the load-bearing mechanisms:

• Pipeline flow — the authoritative phase graph and how phases gate.
• Invariants · Boundaries — the hard rules and package structure.
• Perform build contributors — how artifacts are produced.
• Content-store lifecycle — carrying artifact bytes across phases.
• CI render — how a forge-neutral pipeline becomes native CI YAML.

Proposed models (design of record, not yet built)

• Identity model & governance — first-class orgs/metadata, location-anchored identity, derived {path.*}/{project.module} facts, scoped descriptions, source-tracking presets, and governance as an authority over shared facts. Status and candidate-invariant caveats are stated at the top of that doc.