README
¶
StageFreight
The world's a stage, give it a pipeline.
A declarative lifecycle runtime that governs Git as the source of truth, enforcing operator-defined intent across GitOps workflows, Kubernetes, Docker, and CI ecosystems. StageFreight is open-source, self-building, and replaces fragile shell-script CI pipelines with a single Go binary driven by one .stagefreight.yml file. There's a setting for every stage — this is theatre.
The Canonical Pipeline
You describe intent once in .stagefreight.yml, and StageFreight runs it as a lifecycle — the same five stages whether it's shipping a container image, cutting a cross-forge release, or reconciling a cluster. It even renders your forge's pipeline file for you — stagefreight ci render gitlab writes the .gitlab-ci.yml (also GitHub, Gitea, Forgejo) — so the CI document is a generated artifact StageFreight owns, never hand-maintained.
| Act | What it does | Powered by |
|---|---|---|
| Audition | Prove the change before anything acts on it | lint · tests · policy · config-freshness |
| Perform | The one authoritative build — or, per mode, a reconcile | docker image · binary · gitops · compose |
| Review | Scan what was built, before it can ship | Trivy · Grype · SBOM |
| Publish | The only act that distributes | registries · releases · packages · pages · project metadata |
| Narrate | The report that always runs, even on failure | badges · notifications · run summary |
Git is the source of truth: the acts only enact accepted state — never a merge request, never an unmerged branch. The same binary is both the CI image and your local CLI.
Features:
| Detect → Plan → Build | Finds Dockerfiles, resolves tags from git, builds multi-platform images via docker buildx |
| Multi-Registry Push | Docker Hub, GHCR, GitLab, Quay, Harbor, JFrog, Gitea — with branch/tag filtering via regex (! negation) |
| Security Scanning | Trivy + Grype vulnerability scan, Syft SBOM generation, configurable detail levels per branch or tag |
| Cross-Forge Releases | Create releases on GitLab, GitHub, or Gitea with auto-generated notes, badges, and cross-platform sync |
| Cache-Aware Linting | Parallel lint modules, delta-only on changed files, with JUnit reporting for CI |
| Retention Policies | Restic-style tag retention (keep_last, daily, weekly, monthly, yearly) across all registry providers |
| Self-Building | StageFreight builds, scans, and releases itself through its own pipeline — this image is one of its own artifacts |
Documentation:
| Start Here | Quick-Start Scenarios · Full Docs |
| CLI Reference | Full Command Reference |
| Config Reference | Full Config Schema |
| Manifest Examples | Aspirational Example Configs · Quick Examples |
| Roadmap | Full Vision |
| GitLab | GitLab Integration |
Image Contents
Base Images
Runtime Packages
Contributing
- Fork the repository
- Submit Pull Requests / Merge Requests
- Open issues with ideas, bugs, or feature requests
Disclaimer
The Software provided hereunder is licensed "as-is," without warranties of any kind. The developer makes no promises about functionality, performance, or availability. Not responsible if StageFreight replaces your entire CI pipeline and you find yourself with free time you didn't expect, your retention policies work so well your registry bill drops and finance gets confused, or your release notes become more detailed than the actual features they describe.
Any resemblance to working software is entirely intentional but not guaranteed. The developer claims no credit for anything that actually goes right — that's all you and the unstoppable force of the Open Source community.
License
Distributed under the AGPL-3.0-only License. See licensing for commercial licensing.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
stagefreight-gen-banner
command
Command stagefreight-gen-banner generates a Go source file containing the StageFreight logo as an ANSI-escaped string constant.
|
Command stagefreight-gen-banner generates a Go source file containing the StageFreight logo as an ANSI-escaped string constant. |
|
internal
|
|
|
src
|
|
|
ansible
Package ansible implements the host-convergence lifecycle backend: declared playbooks executed inside a containerized ansible runtime (the execution image) against SSH-managed hosts.
|
Package ansible implements the host-convergence lifecycle backend: declared playbooks executed inside a containerized ansible runtime (the execution image) against SSH-managed hosts. |
|
atomicfile
Package atomicfile provides atomic file write operations.
|
Package atomicfile provides atomic file write operations. |
|
auditionproof
Package auditionproof is the evidence model for audition: audition produces proof results, later phases consume them.
|
Package auditionproof is the evidence model for audition: audition produces proof results, later phases consume them. |
|
badge
Package badge provides a configurable SVG badge engine with dynamic font measurement.
|
Package badge provides a configurable SVG badge engine with dynamic font measurement. |
|
build/contributors
Package contributors holds the build-strategy contributors that supply rows into a perform run's domains.
|
Package contributors holds the build-strategy contributors that supply rows into a perform run's domains. |
|
build/domains
Package domains makes a perform run a single domain-ordered narrative.
|
Package domains makes a perform run a single domain-ordered narrative. |
|
build/engines
Package engines contains all built-in build engines.
|
Package engines contains all built-in build engines. |
|
cas
Package cas is StageFreight's content-addressed artifact store: it retains the exact OCI layout bytes produced by a single perform-stage build so that review and publish operate on those bytes rather than re-deriving the image.
|
Package cas is StageFreight's content-addressed artifact store: it retains the exact OCI layout bytes produced by a single perform-stage build so that review and publish operate on those bytes rather than re-deriving the image. |
|
ci/render/azuredevops
Package azuredevops renders a StageFreight pipeline to an Azure DevOps pipeline.
|
Package azuredevops renders a StageFreight pipeline to an Azure DevOps pipeline. |
|
ci/render/forgejo
Package forgejo renders a StageFreight pipeline to a Forgejo Actions workflow.
|
Package forgejo renders a StageFreight pipeline to a Forgejo Actions workflow. |
|
ci/render/gitea
Package gitea renders a StageFreight pipeline to a Gitea Actions workflow.
|
Package gitea renders a StageFreight pipeline to a Gitea Actions workflow. |
|
ci/render/github
Package github renders a StageFreight pipeline to a GitHub Actions workflow.
|
Package github renders a StageFreight pipeline to a GitHub Actions workflow. |
|
ci/render/gitlab
Package gitlab lowers a forge-neutral model.Pipeline to GitLab CI YAML.
|
Package gitlab lowers a forge-neutral model.Pipeline to GitLab CI YAML. |
|
ci/render/internal/actions
Package actions is a private serialization backend: it writes a forge-neutral model.Pipeline out in the GitHub Actions workflow wire format.
|
Package actions is a private serialization backend: it writes a forge-neutral model.Pipeline out in the GitHub Actions workflow wire format. |
|
ci/render/internal/azurepipelines
Package azurepipelines is a private serialization backend: it writes a forge-neutral model.Pipeline out as an Azure DevOps pipeline (azure-pipelines.yml).
|
Package azurepipelines is a private serialization backend: it writes a forge-neutral model.Pipeline out as an Azure DevOps pipeline (azure-pipelines.yml). |
|
ci/render/model
Package model defines the forge-neutral CI pipeline types.
|
Package model defines the forge-neutral CI pipeline types. |
|
cli
command
|
|
|
cli/cliflag
Package cliflag provides self-describing CLI flag types.
|
Package cliflag provides self-describing CLI flag types. |
|
component
Package component provides GitLab CI component spec parsing and documentation generation for the `stagefreight component` command family.
|
Package component provides GitLab CI component spec parsing and documentation generation for the `stagefreight component` command family. |
|
credentials
Package credentials provides centralized registry credential resolution.
|
Package credentials provides centralized registry credential resolution. |
|
disk
Package disk is a storage-attribution diagnostic for StageFreight: it answers "what operational entity (project / registry / runtime) is consuming disk today" rather than "what folders exist".
|
Package disk is a storage-attribution diagnostic for StageFreight: it answers "what operational entity (project / registry / runtime) is consuming disk today" rather than "what folders exist". |
|
docker
Package docker provides Docker lifecycle orchestration for StageFreight.
|
Package docker provides Docker lifecycle orchestration for StageFreight. |
|
fonts
Package fonts provides embedded TTF fonts shared across StageFreight packages.
|
Package fonts provides embedded TTF fonts shared across StageFreight packages. |
|
forge
Package forge provides a platform-agnostic abstraction over git forges (GitLab, GitHub, Gitea/Forgejo).
|
Package forge provides a platform-agnostic abstraction over git forges (GitLab, GitHub, Gitea/Forgejo). |
|
gitops
Package gitops provides Flux CD graph discovery, change impact analysis, and reconciliation coordination.
|
Package gitops provides Flux CD graph discovery, change impact analysis, and reconciliation coordination. |
|
gitplan
Package gitplan is StageFreight's planner for shared-history git operations.
|
Package gitplan is StageFreight's planner for shared-history git operations. |
|
gitver
Package gitver provides git-based version detection and tag template resolution.
|
Package gitver provides git-based version detection and tag template resolution. |
|
governance
Package governance re-exports preset resolution from src/config.
|
Package governance re-exports preset resolution from src/config. |
|
k8s
Package k8s provides Kubernetes cluster discovery for the k8s-inventory scribe k8s-inventory module.
|
Package k8s provides Kubernetes cluster discovery for the k8s-inventory scribe k8s-inventory module. |
|
lint/modules
Package modules contains all built-in lint modules.
|
Package modules contains all built-in lint modules. |
|
lint/modules/freshness
Package freshness checks for outdated dependencies across ecosystems: Dockerfile base images, pinned tool versions, Go modules, Rust crates, npm packages, Alpine APK, Debian/Ubuntu APT, and pip packages.
|
Package freshness checks for outdated dependencies across ecosystems: Dockerfile base images, pinned tool versions, Go modules, Rust crates, npm packages, Alpine APK, Debian/Ubuntu APT, and pip packages. |
|
lint/modules/vulnerabilities
Package vulnerabilities is the single lint module that reports known vulnerabilities affecting a project's dependencies.
|
Package vulnerabilities is the single lint module that reports known vulnerabilities affecting a project's dependencies. |
|
llm
Package llm dispatches composed stencil bodies to model backends (the llms: library).
|
Package llm dispatches composed stencil bodies to model backends (the llms: library). |
|
manifest
Package manifest defines the StageFreight manifest schema and deterministic JSON serialization.
|
Package manifest defines the StageFreight manifest schema and deterministic JSON serialization. |
|
mirror
Package mirror converges a mirror forge toward a desired release set, granularly and provenance-bounded: it only ever creates/updates/deletes releases IT placed there (marked), never foreign or human-authored ones.
|
Package mirror converges a mirror forge toward a desired release set, granularly and provenance-bounded: it only ever creates/updates/deletes releases IT placed there (marked), never foreign or human-authored ones. |
|
output/layout
Package layout provides terminal-aware text layout primitives.
|
Package layout provides terminal-aware text layout primitives. |
|
output/termutil
Package termutil detects terminal constraints for output layout.
|
Package termutil detects terminal constraints for output layout. |
|
pages
Package pages holds the static-site deploy providers for the `kind: pages` target.
|
Package pages holds the static-site deploy providers for the `kind: pages` target. |
|
paths
Package paths is the single source of truth for where StageFreight writes on disk.
|
Package paths is the single source of truth for where StageFreight writes on disk. |
|
postbuild
Package postbuild contains post-build hook adapters that coordinate between the pipeline framework and external system packages (registry, badge, etc.).
|
Package postbuild contains post-build hook adapters that coordinate between the pipeline framework and external system packages (registry, badge, etc.). |
|
promote
Package promote distributes a content-store OCI layout to a registry WITHOUT rebuilding and WITHOUT a daemon round-trip, preserving the exact index digest that perform recorded and review verified.
|
Package promote distributes a content-store OCI layout to a registry WITHOUT rebuilding and WITHOUT a daemon round-trip, preserving the exact index digest that perform recorded and review verified. |
|
props
Package props implements the composable presentation subsystem.
|
Package props implements the composable presentation subsystem. |
|
provision
Package provision is StageFreight's shared environment-realization surface: the single, honest way every subsystem communicates what tools and native capabilities it pulled in, where from, and how (if at all) it verified them.
|
Package provision is StageFreight's shared environment-realization surface: the single, honest way every subsystem communicates what tools and native capabilities it pulled in, where from, and how (if at all) it verified them. |
|
reconcile
Package reconcile implements repository reconciliation — a class of mutation distinct from dependency updates.
|
Package reconcile implements repository reconciliation — a class of mutation distinct from dependency updates. |
|
registry
Package registry provides a platform-agnostic abstraction over container registries (Docker Hub, GitLab, GHCR, Quay, JFrog, Harbor, Gitea).
|
Package registry provides a platform-agnostic abstraction over container registries (Docker Hub, GitLab, GHCR, Quay, JFrog, Harbor, Gitea). |
|
release
Package release handles release notes generation, release creation, and cross-platform sync.
|
Package release handles release notes generation, release creation, and cross-platform sync. |
|
release/trustdisclosure
Package trustdisclosure interprets a publish ResultsManifest into a STRUCTURED trust disclosure — typed facts, never pre-baked prose.
|
Package trustdisclosure interprets a publish ResultsManifest into a STRUCTURED trust disclosure — typed facts, never pre-baked prose. |
|
retention
Package retention implements a restic-style retention engine that works with any named+timestamped items (registry tags, forge releases, etc).
|
Package retention implements a restic-style retention engine that works with any named+timestamped items (registry tags, forge releases, etc). |
|
runner
Package runner implements execution substrate introspection.
|
Package runner implements execution substrate introspection. |
|
scribe
Package scribe is the scribe engine: it resolves a config's scribe.content / scribe.files into rendered modules and injects them into the workspace's marked regions.
|
Package scribe is the scribe engine: it resolves a config's scribe.content / scribe.files into rendered modules and injects them into the workspace's marked regions. |
|
scribe/render
Package render holds scribe's element producers.
|
Package render holds scribe's element producers. |
|
security
Package security provides vulnerability scanning and SBOM generation.
|
Package security provides vulnerability scanning and SBOM generation. |
|
sign
Package sign is the pure trust-contract core of StageFreight signing.
|
Package sign is the pure trust-contract core of StageFreight signing. |
|
sign/anchordoc
Package anchordoc generates the canonical signing-anchor documentation — a managed, idempotent section embedded in an operator-owned file (conventionally SECURITY.md).
|
Package anchordoc generates the canonical signing-anchor documentation — a managed, idempotent section embedded in an operator-owned file (conventionally SECURITY.md). |
|
sign/autosign
Package autosign resolves the effective signer for a target, applying Tier-0 auto-provision ONLY when the operator has consented (enabled && auto_provision && a configured state_dir).
|
Package autosign resolves the effective signer for a target, applying Tier-0 auto-provision ONLY when the operator has consented (enabled && auto_provision && a configured state_dir). |
|
sign/cosign
Package cosign is the ONLY cosign-aware code in StageFreight signing — the edge renderer that satisfies a sign.SignPlan (a declarative trust contract) against a declared capability Env, emitting a concrete cosign invocation.
|
Package cosign is the ONLY cosign-aware code in StageFreight signing — the edge renderer that satisfies a sign.SignPlan (a declarative trust contract) against a declared capability Env, emitting a concrete cosign invocation. |
|
sign/provision
Package provision manages StageFreight's auto-provisioned Tier-0 signing identity — a persistent software cosign keypair living in the operator's signing state dir.
|
Package provision manages StageFreight's auto-provisioned Tier-0 signing identity — a persistent software cosign keypair living in the operator's signing state dir. |
|
ssh
Package ssh provides SSH authentication and host key resolution for all SSH transports in StageFreight.
|
Package ssh provides SSH authentication and host key resolution for all SSH transports in StageFreight. |
|
stencil
Package stencil is StageFreight's audience-text composition engine — the one lever for every place SF emits text a human reads as the project's voice (scribe README regions, narrate notifications, release bodies, and later tag/ commit messages).
|
Package stencil is StageFreight's audience-text composition engine — the one lever for every place SF emits text a human reads as the project's voice (scribe README regions, narrate notifications, release bodies, and later tag/ commit messages). |
|
substrate
Package substrate realizes the native BUILD ENVIRONMENT a build needs — C toolchains, build helpers, sysroots — as a peer of the toolchain layer, under the same ownership discipline: inferred (engines emit CAPABILITIES, never packages), realized by a backend (which alone knows distro/package semantics), cached on the persistent mount, and recorded as explicit provenance.
|
Package substrate realizes the native BUILD ENVIRONMENT a build needs — C toolchains, build helpers, sysroots — as a peer of the toolchain layer, under the same ownership discipline: inferred (engines emit CAPABILITIES, never packages), realized by a backend (which alone knows distro/package semantics), cached on the persistent mount, and recorded as explicit provenance. |
|
supplychain/analysis
Package analysis is the supply-chain vulnerability analysis layer.
|
Package analysis is the supply-chain vulnerability analysis layer. |
|
supplychain/analysis/evidence
Package evidence is StageFreight's security-ENRICHMENT layer.
|
Package evidence is StageFreight's security-ENRICHMENT layer. |
|
sync
Package sync implements forge accessory synchronization.
|
Package sync implements forge accessory synchronization. |
|
test
Package test is the StageFreight test subsystem: it resolves declared/synthesized test suites into native commands, runs them, and models the verdict.
|
Package test is the StageFreight test subsystem: it resolves declared/synthesized test suites into native commands, runs them, and models the verdict. |
|
toolchain
Package toolchain provides a governed execution substrate for external tools.
|
Package toolchain provides a governed execution substrate for external tools. |
|
trace
Package trace implements the truth emission model for StageFreight.
|
Package trace implements the truth emission model for StageFreight. |
|
vulnerability/severity
Package severity is the vulnerability domain's severity vocabulary: normalization, ranking, and ordering of the well-known labels (critical, high, medium, low, unknown).
|
Package severity is the vulnerability domain's severity vocabulary: normalization, ranking, and ordering of the well-known labels (critical, high, medium, low, unknown). |
|
workspace
Package workspace owns the .stagefreight/ generated namespace and keeps it hygienic.
|
Package workspace owns the .stagefreight/ generated namespace and keeps it hygienic. |
Click to show internal directories.
Click to hide internal directories.