StageFreight — Config Reference¶

Complete reference for the .stagefreight.yml configuration schema (version 1).

For conceptual documentation and usage examples, see: - Docker Build — builds + targets for container images - Release Management — release targets and rolling tags - Narrator & Badges — content composition items - Security Scanning — vulnerability scanning config - Linter Configuration — lint modules and options - Configuration Examples — 24 example manifests

Generated sections below are assembled from docs/modules/config-reference.md via Narrator.

Config Sections¶

version
vars
defaults
forges
repos
registries
signing_profiles
signing
versioning
matchers
builds
targets
lint
security
commit
dependency
narrate
test
manifest
release
ci
lifecycle
governance
gitops
docker
build_cache
glossary
presentation
tag
toolchains

version¶

Schema version number. Must be 1 — the first stable schema.

Name	YAML Key	Type	Required	Default	Description
`version`	`version`	int	Yes	—	Version must be 1. The pre-version config was an unversioned alpha that never earned a schema number — this is the first stable schema.

Example:

version: 1

vars¶

User-defined template variable dictionary. Referenced as {var:name} anywhere templates are resolved.

Name	YAML Key	Type	Required	Default	Description
`vars`	`vars`	map[string]string	No	—	Vars is a user-defined template variable dictionary. Referenced as {var:name} anywhere templates are resolved.

Example:

vars:
  org: prplanit
  repo: stagefreight

defaults¶

Defaults is inert YAML anchor storage. StageFreight ignores this section entirely — it exists for users to define &anchors.

forges¶

Forges declares git hosts. Each entry is a host identity (provider, URL, credentials).

forges:
  - id: <string>   # unique identifier (e.g., "prplanit-gitlab") · required
    provider: <string>   # gitlab, github, gitea · one of: gitlab, github, gitea, forgejo, azuredevops · required
    url: <string>   # base URL (e.g., "https://gitlab.prplanit.com") · required
    credentials: <string>   # env var prefix for token resolution

repos¶

Repos declares projects on forges. References forges by id. Has role (primary/mirror).

repos:
  - id: <string>   # unique identifier · required
    forge: <string>   # references forges[].id · required
    project: <string>   # project path on the forge (e.g., "{var:gitlab_group}/{var:repo}") · required
    roles: [<string>]   # ["primary"] | ["mirror"] | ["mirror", "publish-origin"] | []
    branches:   # branch identity (default, protected, etc.)
      default: <string>   # Default is the default branch name (e.g., "main"). Required for primary.
    worktree: <string>   # local working tree path (primary only)
    ref: <string>   # pinned ref for non-primary repos (governance, presets)
    sync:   # mirror sync domains
      git: false   # Git enables authoritative mirror replication via git push --mirror. All refs, branches, tags…
      releases: false   # Releases enables forge-native release projection (notes, assets, links). Runs after git mirror…
      docs: false   # Docs enables README/doc file projection via forge commit API. Mutually exclusive with Git (docs…

registries¶

Registries declares OCI registry hosts. Referenced by targets.

registries:
  - id: <string>   # unique identifier (e.g., "dockerhub") · required
    provider: <string>   # docker, harbor, ghcr, quay, gitea, generic · one of: acr, docker, dockerhub, ecr, forgejo, gar, generic, ghcr, gitea, github, gitlab, harbor, jfrog, local, nexus, quay · required
    url: <string>   # registry URL (e.g., "docker.io") · required
    credentials: <string>   # env var prefix for token resolution
    default_path: <string>   # default image path (e.g., "{var:org}/{var:repo}")

signing_profiles¶

Named trust profiles for signing release artifacts and images. A profile declares a trust CLASS (requires: key | oidc | kms | hardware) and assurance requirements — never a device, vendor, or cosign flag. Targets reference a profile by id via signing_profile: <id> (same pattern as registry:). With no profile, the implicit legacy default signs images when COSIGN_KEY resolves; checksum blobs (SHA256SUMS) sign only under an explicit profile.

signing_profiles:
  - id: <string>   # required
    requires: [<string>]   # trust class(es); v1 enforces exactly one · one of: hardware, key, kms, oidc · required
    key:   # Class reference blocks — at most one, matching the declared class.
      ref: <string>   # required
    oidc:
      issuer: <string>
      identity: <string>
    kms:
      ref: <string>   # required
    pkcs11:   # hardware transport selector (optional; absent = FIDO2 --sk)
      ref: <string>   # required
    physical_presence: <string>   # Assurance properties (hardware-class ONLY; enforced in validation). The value is the keyword…
    non_exportable: <string>
    transparency_log: false   # TransparencyLog overrides the per-class default (on for oidc, off otherwise).
    attestation: false   # Attestation also emits a provenance attestation alongside the signature.
    enforce: false   # Enforce makes a signing failure fatal to the phase (default: best-effort — warn + record a failed…
    allow_fallback: false   # AllowFallback permits an explicitly-configured signer that fails to resolve to fall back to the…

requires names the trust class only — machinery names (yubikey/fido2/vault/aws) are rejected as classes. physical_presence (value required) is valid only for requires: hardware; non_exportable is valid for hardware OR kms. Hardware transport is deployment wiring: a hardware profile may carry pkcs11: { ref: <name> }, bound via SF_PKCS11_<REF> to a full pkcs11: URI, e.g. SF_PKCS11_RELEASE='pkcs11:slot-id=0;id=%02;object=SIGN%20key?module-path=/usr/lib/x86_64-linux-gnu/libykcs11.so' (YubiKey PIV slot 9c = the digital-signature slot, ykcs11 object id 2). With no pkcs11 ref the hardware class falls back to FIDO2 (cosign --sk). The module path / slot / PIN policy live in the env URI, never in the profile. KMS/Vault ref binding is deployment wiring: set SF_KMS_<REF> to the URI, e.g. SF_KMS_RELEASE-SIGNING-KEY=hashivault://release (cosign's hashivault:// takes the key NAME only). OIDC/keyless trust domain is deployment wiring too: SF_SIGSTORE_{DOMAIN,FULCIO,REKOR,ISSUER,TRUSTED_ROOT,IDENTITY_TOKEN}. Setting FULCIO/REKOR/TRUSTED_ROOT points cosign at a self-hosted Sigstore (public Fulcio won't trust a self-hosted issuer); ISSUER falls back to the profile's oidc.issuer; IDENTITY_TOKEN (value or path) supplies the OIDC token for unattended/non-CI signing (ambient providers used when unset). Standing up Fulcio/Rekor is operator infrastructure, not StageFreight. enforce: true makes a signing failure fatal; the default is best-effort (recorded as a failed outcome, the build proceeds). Aliases normalized at load: keyless → oidc, yubikey → hardware.

signing¶

Operational signing configuration (distinct from signing_profiles). Governs whether StageFreight may sign, whether it may create/manage a Tier-0 software identity on your behalf, and where that identity persists. enabled and auto_provision are deliberately separate — "signing is encouraged" and "the system minted an identity for me" are not the same thing.

signing:
  enabled: false   # nil/true = signing allowed; false = all signing off
  auto_provision: false   # explicit consent to create/manage a Tier-0 identity
  state_dir:   # where persistent signing material lives
    type: <string>   # "volume" | "host_path"
    name: <string>   # volume name (type: volume)
    path: <string>   # absolute path (type: host_path)

enabled: false disables ALL signing regardless of profiles/keys. auto_provision: true requires a state_dir — with no durable storage an ephemeral key would break trust continuity every run. With auto_provision: false (default), StageFreight never creates key material — it signs only with an explicit COSIGN_KEY/profile. Opinionated always-on belongs in a runner/distribution config, not core. The Tier-0 identity is created once and NEVER silently regenerated: drift, partial state, or an orphan key is fatal. The state_dir must live outside the repository (a key there could be committed, baked into an image, or published).

versioning¶

Versioning controls how version identity is derived from git state.

versioning:
  preset: <string>
  tag_sources:   # TagSources defines named places where version bases can come from. e.g., {id: "stable", pattern… · required
    - id: <string>   # ID is the unique identifier (e.g. "stable", "prerelease"). Referenced by branch_builds[].base_from… · required
      pattern: <string>   # Pattern is the regex that identifies tags belonging to this source. e.g., "^v?\\d+\\.\\d+\\.\\d+$" · required
  branch_builds:   # BranchBuilds defines version format for non-tag commits per branch. Evaluated in declaration order…
    - id: <string>   # ID is the unique identifier. "default" is the catch-all entry and must appear last in the… · required
      match: <string>   # Match references a declared branch matcher name. Required for named branch_builds entries. The…
      base_from: [<string>]   # BaseFrom is the ordered fallback chain of tag_sources ids. The runtime walks this list in order… · required
      format: <string>   # Format is the version template for non-release commits. Supported placeholders: {base}, {sha}… · required
  no_lineage:   # NoLineage defines behavior when no tag lineage exists (no matching tags).
    mode: <string>   # Mode controls the response to missing lineage. "error" (default): fail fast with explanation and…
    version: <string>   # Version is the template used when mode is "explicit". Must contain {sha} or {time} — hardcoded…

matchers¶

Matchers defines reusable named patterns for branches (and future dimensions). Pattern definitions only — no behavior. Referenced by branch_builds[].match and target.when.branches.

matchers:
  preset: <string>
  branches: {}   # Branches maps matcher names to regex patterns for branch matching. e.g., "main": "^main$" · required

builds¶

Named build artifacts. Each build has a unique ID referenced by targets. Currently supports kind: docker.

`kind: docker`¶

builds:
  - id: <string>   # ID is the unique identifier for this build, referenced by targets. · required
    kind: docker   # Kind is the build type. Determines which fields are valid. Supported: "docker", "binary"… · one of: binary, command, docker · required
    dockerfile: <string>   # Dockerfile is the path to the Dockerfile. Default: auto-detect.
    context: <string>   # Context is the Docker build context path. Default: "." (repo root).
    target: <string>   # Target is the --target stage name for multi-stage builds.
    platforms: [<string>]   # Platforms lists the target platforms. Default: [linux/{current_arch}].
    build_args: {}   # BuildArgs are key-value pairs passed as --build-arg. Supports templates.

`kind: binary`¶

builds:
  - id: <string>   # ID is the unique identifier for this build, referenced by targets. · required
    kind: binary   # Kind is the build type. Determines which fields are valid. Supported: "docker", "binary"… · one of: binary, command, docker · required
    builder: <string>   # Builder is the toolchain that interprets the build. Supported: "go". Future: "rust", "zig", "cargo". · one of: android, c, dotnet, elixir, go, jvm, node, python, rust
    from: <string>   # From is the source/input root or entry point. e.g., "./src/cli" (Go package), "./src/main.rs"…
    output: <string>   # Output is the artifact name. Windows platforms auto-append ".exe". Default: basename of From.
    args: [<string>]   # Args are ordered raw arguments passed directly to the selected builder. For Go: raw args to "go…
    env: {}   # Env are build environment variables. e.g., {"CGO_ENABLED": "0"}
    platforms: [<string>]   # Platforms lists the target platforms. Default: [linux/{current_arch}].

`kind: command`¶

builds:
  - id: <string>   # ID is the unique identifier for this build, referenced by targets. · required
    kind: command   # Kind is the build type. Determines which fields are valid. Supported: "docker", "binary"… · one of: binary, command, docker · required
    image: <string>   # Image is the container image a containerized build (builder: node, elixir) runs inside (with the…
    command: <string>   # Command is the builder subcommand (binary: e.g. "build") or the full command (kind: command).…
    env: {}   # Env are build environment variables. e.g., {"CGO_ENABLED": "0"}
    stage:   # Stage recycles a binary build's output into this docker build's context before buildx, so a…
      from: <string>   # required
      as: <string>   # required
    outputs:   # Outputs declares what the command produced and each output's artifact class.
      - type: <string>   # one of: binary, file, tree · required
        source: <string>   # required
        worktree: {}

Build IDs must be unique across all builds. Targets reference builds by name via the build: field.

targets¶

Distribution targets and side-effects. Each target has a kind that determines its behavior: push images, sync READMEs, publish components, or create releases.

`kind: registry`¶

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: registry   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    registry: <string>   # Registry references a registries[].id for registry/docker-readme targets. When set…
    build: <string>   # Build references a BuildConfig.ID. Required for kind: registry.
    tags: [<string>]   # Tags are tag templates resolved against version info (kind: registry). e.g., ["{version}"…
    signing_profile: <string>   # SigningProfile references a signing_profiles[].id — the trust profile this target signs under.…
    native_scan: false   # NativeScan enables post-push vulnerability scanning via the registry's own built-in scanner.…
    retention:   # Retention controls cleanup of old tags/releases. Structured only in v2 (no scalar shorthand).
      keep_last: <int>   # keep the N most recent tags · required
      keep_daily: <int>   # keep one per day for the last N days · required
      keep_weekly: <int>   # keep one per week for the last N weeks · required
      keep_monthly: <int>   # keep one per month for the last N months · required
      keep_yearly: <int>   # keep one per year for the last N years · required
      protect: [<string>]   # tag patterns that are never deleted (v2) · required
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

`kind: docker-readme`¶

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: docker-readme   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    registry: <string>   # Registry references a registries[].id for registry/docker-readme targets. When set…
    file: <string>   # File is the path to the README file (kind: docker-readme).
    link_base: <string>   # LinkBase is the base URL for relative link rewriting (kind: docker-readme).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

`kind: gitlab-component`¶

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: gitlab-component   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    spec_files: [<string>]   # SpecFiles lists component spec file paths (kind: gitlab-component).
    catalog: false   # Catalog enables GitLab Catalog registration (kind: gitlab-component).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

`kind: release`¶

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: release   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    aliases: [<string>]   # Aliases are rolling git tag aliases (kind: release). e.g., ["{version}", "{major}.{minor}"…
    tag: <string>   # Tag is the immutable identity pattern for a release channel (kind: release). Distinct from Aliases…
    archives: <string>   # Archives references a binary-archive target ID (kind: release and generic-package).
    prerelease: false   # Prerelease marks the forge release as a pre-release (kind: release). Honored natively by…
    mirror: <string>   # Mirror references a sources.mirrors[].id for release sync. Forge identity (provider, url…
    sync_release: false   # SyncRelease syncs release notes + tags to a remote forge (kind: release, remote only).
    sync_assets: false   # SyncAssets syncs scan artifacts to a remote forge (kind: release, remote only).
    signing_profile: <string>   # SigningProfile references a signing_profiles[].id — the trust profile this target signs under.…
    retention:   # Retention controls cleanup of old tags/releases. Structured only in v2 (no scalar shorthand).
      keep_last: <int>   # keep the N most recent tags · required
      keep_daily: <int>   # keep one per day for the last N days · required
      keep_weekly: <int>   # keep one per week for the last N weeks · required
      keep_monthly: <int>   # keep one per month for the last N months · required
      keep_yearly: <int>   # keep one per year for the last N years · required
      protect: [<string>]   # tag patterns that are never deleted (v2) · required
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

`kind: binary-archive`¶

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: binary-archive   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    build: <string>   # Build references a BuildConfig.ID. Required for kind: registry.
    name: <string>   # Name is the archive filename template (kind: binary-archive). Supports: {id}, {version}, {os}…
    format: <string>   # Format is the archive format: "tar.gz", "zip", "auto", or "binary" (kind: binary-archive). "auto"… · one of: auto, binary, tar.gz, zip
    binary_name: <string>   # BinaryName overrides the binary name inside the archive (kind: binary-archive). Auto-detected from…
    include: [<string>]   # Include lists extra files to bundle into the archive (kind: binary-archive). e.g., ["README.md"…
    checksums: false   # Checksums generates a SHA256SUMS file alongside archives (kind: binary-archive).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

`kind: generic-package`¶

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: generic-package   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    repo: <string>   # Repo references a repos[].id (kind: generic-package). The forge identity (provider, url, project…
    package: <string>   # Package is the generic package name (kind: generic-package). Defaults to the repo project's…
    version: <string>   # Version is the immutable package version pattern (kind: generic-package). Resolved against version…
    archives: <string>   # Archives references a binary-archive target ID (kind: release and generic-package).
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

`kind: pages`¶

targets:
  - id: <string>   # ID is the unique identifier for this target (logging, status, enable/disable). · required
    kind: pages   # Kind is the target type. Determines which fields are valid. · one of: binary-archive, docker-readme, generic-package, gitlab-component, pages, registry, release · required
    provider: <string>   # Provider is the vendor type for auth and API behavior. Registry: docker, ghcr, gitlab, jfrog… · one of: cloudflare, github
    build: <string>   # Build references a BuildConfig.ID. Required for kind: registry.
    dir: <string>   # Dir publishes a repo directory directly instead of a build's output tree (kind: pages). Exactly one…
    domain: [<string>]   # Domain is the custom domain(s) (kind: pages). Accepts a bare scalar or a list:
    project: <string>   # Project is the Cloudflare Pages project name (provider: cloudflare). Default: the target id.…
    base_path: <string>   # BasePath is the URL path the site is served under (kind: pages). Inferred per provider (Cloudflare…
    exclude: [<string>]   # Exclude drops matching paths from the publish workspace before deploy (kind: pages). Globs, applied…
    when:   # When specifies routing conditions for this target.
      branches: [<string>]   # Branches lists branch filters. Each entry is a policy name or "re:<regex>". Empty = no branch…
      git_tags: [<string>]   # GitTags lists git tag filters. Each entry is a policy name or "re:<regex>". Empty = no tag…
      events: [<string>]   # Events lists CI event type filters. Supported: push, tag, release, schedule, manual, pull_request… · one of: manual, merge_request, pull_request, push, release, schedule, tag
      forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…

Target IDs must be unique across all targets. The when block controls routing: all non-empty fields must match (AND logic).

lint¶

Linting configuration. Controls scan mode, module toggles, and per-module options. 9 modules: tabs, secrets, conflicts, filesize, linecount, unicode, yaml, lineendings, freshness.

lint:
  preset: <string>
  level: <string>   # one of: changed, full · required
  cache_dir: <string>   # required
  target_branch: <string>   # required
  exclude: [<string>]   # required
  modules: {}   # required
  provenance:
    generated: [<string>]
    vendored: [<string>]
  remediation:
    trailing_whitespace: false   # default ON under --fix-safe
    final_newline: false   # default ON under --fix-safe
  cache:
    max_age: <string>   # evict entries not hit in this duration (e.g. "7d")
    max_size: <string>   # evict oldest entries when cache exceeds this (e.g. "100MB")
  fail_on: <string>   # FailOn is the DIAGNOSTIC-IMPORTANCE threshold at or above which a lint finding blocks the build…

security¶

Security scanning configuration. Controls vulnerability scanning (Trivy, Grype), SBOM generation (Syft), and how security info appears in release notes.

security:
  preset: <string>
  enabled: false   # run vulnerability scanning (default: true) · required
  required: false   # failure is hard pipeline fail (default: false)
  scanners:   # per-scanner toggles · required
    trivy: false   # run Trivy image scan (default: true)
    grype: false   # run Grype image scan (default: true)
  sbom: false   # generate SBOM artifacts (default: true) · required
  fail_on_critical: false   # DEPRECATED: use fail_on. Alias — true → fail_on: critical. · required
  output: <string>   # directory for scan artifacts (default: .stagefreight/security) · required
  fail_on: <string>   # FailOn is the severity threshold at or above which the scan fails the build: "critical" | "high" |…
  unreachable_vulns: <string>   # UnreachableVulns is the policy for vulnerabilities a reachability analyzer proved are never called…
  release_detail: <string>   # ReleaseDetail is the default detail level for security info in release notes. Values: "none"… · required
  release_detail_rules:   # ReleaseDetailRules are conditional overrides evaluated top-down (first match wins). Uses the… · required
    - tag: <string>   # Tag is a pattern matched against the git tag (CI_COMMIT_TAG). Only evaluated when a tag is present.…
      branch: <string>   # Branch is a pattern matched against the git branch (CI_COMMIT_BRANCH). Prefix with ! to negate.
      detail: <string>   # Detail is the detail level to use when this rule matches. Values: "none", "counts", "detailed"… · required
  cache:   # Cache controls persistent vulnerability DB caching per scanner. Each tool's max_size triggers…
    trivy:
      max_size: <string>   # e.g. "500MB" — full-clear when exceeded
      max_age: <string>   # e.g. "7d" — full-clear when oldest file exceeds age
    grype:
      max_size: <string>   # e.g. "500MB" — full-clear when exceeded
      max_age: <string>   # e.g. "7d" — full-clear when oldest file exceeds age
  overwhelm_message: [<string>]   # OverwhelmMessage is the message lines shown when >1000 vulns are found. Defaults to ["…maybe… · required
  overwhelm_link: <string>   # OverwhelmLink is an optional URL appended after OverwhelmMessage. Defaults to a Psychology Today… · required

commit¶

Commit subsystem configuration. Controls conventional commit formatting, type registry, and default behavior for stagefreight commit.

commit:
  preset: <string>
  default_type: <string>
  default_scope: <string>
  skip_ci: false
  push: false
  conventional: false   # required
  backend: <string>
  types:
    - key: <string>   # required
      label: <string>   # required
      alias_for: <string>
      force_bang: false

dependency¶

Dependency holds configuration for the dependency update subsystem.

dependency:
  preset: <string>
  enabled: false   # required
  output: <string>   # required
  scope:   # required
    go_modules: false   # required
    dockerfile_env: false   # umbrella for docker-image + github-release · required
  commit:   # required
    enabled: false   # required
    type: <string>   # required
    message: <string>   # required
    push: false   # required
    skip_ci: false   # required
    promotion: <string>   # "direct" or "mr" · required
    mr:   # required
      branch_prefix: <string>   # default: "stagefreight/deps" · required
      target_branch: <string>   # default: "" (CI default branch) · required
    run_from:   # gate mutation to declared origin
      allow: [<string>]   # permitted origins: "primary"
      mismatch: <string>   # "read-only" (default), "exit", "ignore"
  ci:   # required
    handoff: <string>   # default: continue · required
  ignore:
    - id: <string>   # e.g. "GHSA-xxxx-yyyy-zzzz", "GO-2026-1234" · required
      reason: <string>   # why this risk is carried
      until: <string>   # YYYY-MM-DD; past this date the ignore lapses
  remediate: false   # Remediate controls whether the update pass PATCHES eligible dependencies (true, default —…
  fail_on: <string>   # FailOn is the vulnerability-severity threshold at or above which a RESIDUAL vulnerability — one…
  policy: <string>   # Policy is the freshness SCOPE — which non-vulnerable dependencies to pursue: "all" (default —…
  max_update: <string>   # MaxUpdate is the update-type CEILING — how far a dependency may move: "major" (allow the…
  min_release_age: <string>   # MinReleaseAge is the supply-chain COOLDOWN: a release younger than this is not recommended…

narrate¶

Narrate configures the Narrate phase (badges, patches, commit). Presence-enabled; dissolves the old docs:/badges:/narrator: surface. Reference docs are a kind: command build committed via narrate.commit.builds, not a subsystem here.

narrate:
  badges:   # Badges are SVG badge definitions rendered from build metadata (was top-level `badges.items`).…
    - id: <string>   # stable user-defined ID for narrator reference · required
      text: <string>   # left side label · required
      value: <string>   # right side value (templates: {env:*}, {sha}, {base}, etc.) · required
      color: <string>   # hex color or "auto" · required
      output: <string>   # SVG output path (required) · required
      link: <string>   # clickable URL
      font: <string>   # font name override
      font_size: <int>   # font size override
  patches:   # Patches are generic marked-region replacements in files (was `narrator:`): each entry names a file…
    - file: <string>   # File is the path to the target file (required). · required
      link_base: <string>   # LinkBase is the base URL for relative link rewriting.
      items: []   # discriminated union by kind — see per-kind blocks below
  commit:   # Commit is the auto-commit action for generated output (was `docs.commit`).
    type: <string>   # conventional type; default: engine's
    message: <string>
    add: [<string>]
    push: false
    skip_ci: false
    run_from:   # gate mutation to declared origin
      allow: [<string>]   # permitted origins: "primary"
      mismatch: <string>   # "read-only" (default), "exit", "ignore"

patches items · `kind: badge`¶

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: badge   # Kind is the item type: badge, shield, text, component, break, include. · required
  text: <string>   # Text is the badge label (left side text).
  value: <string>   # Value is the badge value (right side text, supports templates).
  color: <string>   # Color is the badge color (hex or "auto").
  font: <string>   # Font is the badge font name override.
  font_size: <int>   # FontSize is the badge font size override.
  output: <string>   # Output is the SVG output path for badge generation.
  link: <string>   # Link is the clickable URL (kind: badge, shield).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · `kind: shield`¶

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: shield   # Kind is the item type: badge, shield, text, component, break, include. · required
  shield: <string>   # Shield is the shields.io path (kind: shield).
  link: <string>   # Link is the clickable URL (kind: badge, shield).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · `kind: text`¶

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: text   # Kind is the item type: badge, shield, text, component, break, include. · required
  content: <string>   # Content is raw text/markdown content (kind: text).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · `kind: component`¶

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: component   # Kind is the item type: badge, shield, text, component, break, include. · required
  spec: <string>   # Spec is the component spec file path (kind: component).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · `kind: include`¶

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: include   # Kind is the item type: badge, shield, text, component, break, include. · required
  path: <string>   # Path is the file path to include verbatim (kind: include).
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · `kind: build-contents`¶

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: build-contents   # Kind is the item type: badge, shield, text, component, break, include. · required
  build: <string>   # Build is the id of the build whose manifest this item renders (kind: build-contents). Ownership is…
  source: <string>   # Source is an optional path to a manifest JSON file (kind: build-contents). If omitted, uses the…
  section: <string>   # Section is the dot-path into the manifest (kind: build-contents). e.g., "inventories.pip"…
  renderer: <string>   # Renderer is the rendering format (kind: build-contents). Supported: "table", "list", "kv".
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

patches items · `kind: break`¶

- id: <string>   # ID is the item identifier (unique within file). · required
  kind: break   # Kind is the item type: badge, shield, text, component, break, include. · required
  placement:   # Placement declares where this item goes in the target file. · required
    between: <value>   # Between is a two-element array: [start_marker, end_marker]. Content is placed relative to these…
    after: <string>   # After is a regex/literal line match (reserved for future use).
    before: <string>   # Before is a regex/literal line match (reserved for future use).
    heading: <string>   # Heading is a markdown heading match (reserved for future use).
    mode: <string>   # Mode controls how content is placed: replace (default), append, prepend, above, below.
    inline: false   # Inline renders items side-by-side when true (default: false).

test¶

test:
  preset: <string>
  enabled: false   # required
  auto: false   # nil ⇒ true
  suites:
    - id: <string>   # required
      tool: <string>   # required
      gate: <string>   # default: perform
      from: <string>   # module/crate dir when not at repo root (e.g. dd-ui's api/)
      args: [<string>]   # raw passthrough escape hatch
      command: <string>
      packages: [<string>]   # ── Go (native `go test` flag projections)…
      tags: [<string>]   # -tags a,b
      run: <string>   # -run <regex>
      timeout: <string>   # -timeout <d>
      race: false   # -race
      coverage: false   # -coverprofile
      coverage_min: <value>   # gate: fail the suite if statement coverage < this %
      workspace: false   # ── Rust (native `cargo test` flag projections)…
      features: [<string>]   # --features a,b
      tests: [<string>]   # --test <name>
      release: false   # --release
      nextest: false   # cargo nextest run

manifest¶

Manifest holds configuration for the manifest subsystem.

manifest:
  preset: <string>
  enabled: false   # Enabled controls whether manifest generation is active (default: false). · required
  mode: <string>   # Mode controls where the manifest is stored. ephemeral: temp location, use during run, discard… · one of: commit, ephemeral, publish, workspace
  output_dir: <string>   # OutputDir is the output directory for manifest files. Default: .stagefreight/manifests

release¶

Release holds configuration for the release subsystem.

release:
  preset: <string>
  enabled: false   # required
  required: false   # failure is hard pipeline fail (default: false)
  security_summary: <string>   # required
  registry_links: false   # required
  catalog_links: false   # required
  run_from:   # gate mutation to declared origin
    allow: [<string>]   # permitted origins: "primary"
    mismatch: <string>   # "read-only" (default), "exit", "ignore"

ci¶

CI holds all pipeline-related configuration consumed by ci render.

ci:
  image: <string>   # Image is the container image for all pipeline jobs. Required — render refuses to emit without it. · required
  routing:   # Routing declares per-phase runner placement requirements. The renderer lowers labels to…
    default:
      labels: [<string>]
    audition:
      labels: [<string>]
    perform:
      labels: [<string>]
    review:
      labels: [<string>]
    publish:
      labels: [<string>]
    narrate:
      labels: [<string>]

lifecycle¶

Selects the repository lifecycle mode — the phase graph the pipeline runs. The single most architecturally significant config choice: it determines whether the repo builds container images, validates GitOps manifests, or reconciles governance. When omitted, the lifecycle defaults to image.

lifecycle:
  preset: <string>   # Preset references an external lifecycle fragment to inherit (the generic preset: fragment-include…
  mode: <string>   # Mode selects the phase graph. Empty defaults to image. image — build → review → publish image… · required

Phase applicability is mode-derived: the review and publish phases do work only in image mode; gitops, governance, and docker mark them not_applicable. Capability requirements differ per mode (e.g. gitops requires Reconcile + ImpactAnalysis, plus ClusterAuth when gitops.cluster is set); the lifecycle backend is checked against them at plan time.

governance¶

Governance defines configuration for the governance lifecycle mode. Only valid in the control repo (lifecycle.mode: governance).

governance:
  clusters:   # required
    - id: <string>   # required
      targets:   # required
        repos: [<string>]
        groups:
          - id: <string>
            repos: [<string>]   # required
        credentials: <string>   # env var prefix for forge auth
      stagefreight: {}   # required

gitops¶

GitOps defines configuration for the gitops lifecycle mode.

gitops:
  preset: <string>
  backend: <string>   # Backend selects the GitOps reconciliation backend (e.g. "flux", "argo"). · required
  cluster:   # Cluster defines the target Kubernetes cluster. · required
    name: <string>   # required
    server: <string>   # required
    exposure:   # required
      rules:   # required
        - level: <string>   # internet | intranet | cluster · required
          endpoints: [<string>]   # ip:port (highest precedence) · required
          gateways: [<string>]   # required
          cidrs: [<string>]   # required
          ports: [...]   # AND with CIDRs (empty = any port) · required
          service_types: [<string>]   # ClusterIP | NodePort | LoadBalancer · required
  oidc:   # OIDC defines authentication configuration for the cluster. · required
    audience: <string>   # required

docker¶

Docker defines configuration for the docker lifecycle mode.

docker:
  preset: <string>
  backend: <string>   # Backend selects the Docker execution engine (e.g. "compose"). · required
  targets:   # Targets defines how reconciliation targets are resolved. · required
    source: <string>   # Source is the inventory adapter (e.g. "ansible"). · required
    inventory: <string>   # Inventory is the path to the inventory file (relative to repo root). · required
    selector:   # Selector declares which hosts from inventory are eligible. · required
      groups: [<string>]   # required
  iac:   # IaC defines the Infrastructure as Code directory layout. · required
    path: <string>   # Path is the IaC directory relative to repo root (default: "docker-compose"). · required
  secrets:   # Secrets defines the secrets decryption provider. · required
    provider: <string>   # Provider selects the secrets backend (e.g. "sops", "vault", "infisical"). · required
  drift:   # Drift defines drift detection and reconciliation policy. · required
    tier2_action: <string>   # report | reconcile (default: report) · required
    orphan_action: <string>   # report | down | prune (default: report) · required
    orphan_threshold: <int>   # block if more than N orphans (default: 5) · required
    prune_requires_confirmation: false   # require --force for prune (default: true) · required

build_cache¶

BuildCache defines the build cache subsystem (local, shared, hybrid).

build_cache:
  preset: <string>
  mode: <string>   # Mode selects which cache planes are active. "": inactive — no cache flags emitted, no cleanup…
  builder:   # Builder configures the buildx builder lifecycle. The engine owns creation, bootstrap, and narration…
    backend: <string>   # Backend pins the build backend. Default: "" (auto-detect). "buildkitd" → prefer persistent…
    name: <string>   # Name is the buildx builder name. Default: "sf-builder".
    driver: <string>   # Driver is the buildx driver. Default: "docker-container".
    context: <string>   # Context is the Docker context name for the builder endpoint. Default: "sf-context".
  local:   # Local configures the bounded local buildkit cache.
    path: <string>   # override local cache root (default: /stagefreight/cache/buildkit)
    retention:
      max_age: <string>   # e.g. "7d"
      max_size: <string>   # e.g. "15GB"
  external:   # External configures registry-backed shared cache.
    target: <string>   # Target references a targets[].id with kind: registry.
    path: <string>   # Path is appended to the target URL: <target-url>/<path>/<repo>/<branch>.
    fallback: <string>   # Fallback is the read-only fallback branch ref (e.g. "default", "main"). Never written to unless…
    mode: <string>   # Mode is the BuildKit cache mode (e.g. "max", "min"). Default: "max".
    retention:   # Retention defines when stale external cache refs are pruned.
      max_refs: <int>   # max branch cache refs per repo
      stale_age: <string>   # prune refs for dead/merged branches
  cleanup:   # Cleanup is governance-owned host-hygiene policy — see HostCleanupConfig.
    enabled: false   # Enabled controls whether cleanup runs. Independent of cache mode.
    enforcement: <string>   # Enforcement controls what happens when cleanup cannot execute. best_effort: continue + structured…
    protect:   # Protect defines what is never pruned.
      images:
        refs: [<string>]   # glob patterns
      volumes:
        named: false   # protect all named volumes
    prune:   # Prune defines what is eligible for removal.
      images:
        dangling:
          older_than: <string>   # e.g. "72h"
        unreferenced:
          older_than: <string>   # e.g. "72h"
      build_cache:
        older_than: <string>   # e.g. "72h"
        keep_storage: <string>   # e.g. "20GB"
      containers:
        exited:
          older_than: <string>   # e.g. "72h"
      networks:
        unused: false

glossary¶

Glossary defines the repo's shared change-language model. Consumed by commit authoring, tag planning, and release rendering.

glossary:
  preset: <string>
  types: {}   # required
  breaking:   # required
    aliases: [<string>]   # e.g., [b, break, bc]
    bang_suffix: false   # feat! syntax · required
    footer_keys: [<string>]   # e.g., ["BREAKING CHANGE"] · required
    force_highlight: false   # required
    priority_boost: <int>   # required
  filters:   # required
    summary:   # required
      strip_phrases: [<string>]
      strip_regex: [<string>]
    trailers:   # required
      strip_keys: [<string>]
    normalize_whitespace: false   # required
  rewrites:   # required
    phrases:
      - from: <string>   # required
        to: <string>   # required
    regex:
      - pattern: <string>   # required
        replace: <string>   # required
  render:   # required
    empty_strategy: <string>   # prompt | fail | allow_empty · required

presentation¶

Presentation defines surface-specific rendering policies.

presentation:
  preset: <string>
  commit:   # required
    preserve_raw_subject: false   # required
    enforce_conventional: false   # required
  tag:   # required
    max_entries: <int>   # required
    group_by_type: false   # required
    style: <string>   # concise | explanatory | technical · required
    include_release_visible_only: false   # required
    collapse_similar: false   # required
  release:   # required
    max_entries: <int>   # required
    group_by_type: false   # required
    style: <string>   # concise | explanatory | technical · required
    include_release_visible_only: false   # required

tag¶

Tag holds workflow defaults for the tag planner.

tag:
  preset: <string>
  defaults:   # required
    target: <string>   # default ref to tag (default: HEAD) · required
    preview: false   # show preview before creating · required
    require_approval: false   # require interactive approval · required
    push: false   # push after creation · required
  message:   # required
    mode: <string>   # auto | prompt_if_missing | require_manual · required
    empty_strategy: <string>   # prompt | fail | allow_empty · required

toolchains¶

Toolchains defines operator control over external tool resolution. Version pins, future retention policy, future trust settings.

toolchains:
  desired: {}   # Desired declares intended tool constraints. Authoritative — not a hint. If a desired constraint…