Skip to content

Config.md

Latest commit

 

History

History
1169 lines (994 loc) · 54 KB

Config.md

File metadata and controls

1169 lines (994 loc) · 54 KB
Raw

StageFreight — Config Reference

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

For conceptual documentation and usage examples, see:

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

Config Sections

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.

preset_source

PresetSource is governance-distribution metadata: where a satellite's presets were frozen from (forge coords + pinned ref + cache policy). Written by governance reconcile; IGNORED at runtime today — the committed .stagefreight/preset-cache is authoritative — but declared so a governed config decodes under KnownFields(true). Consumed only if/when runtime pinned-external resolution is built.

preset_source:
  provider: <string>
  repo_url: <string>
  project_id: <string>
  ref: <string>
  cache_policy: <string>

forges

Forges declares git hosts as an id→forge map (provider, URL, credentials).

forges:
  <id>:   # entry key = the unique id
    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 as an id→repo map. References forges by id. Has role.

repos:
  <id>:   # entry key = the unique id
    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
      branches:
        scope: <string>   # "current" | "all" (exact expands here)
        prune: false   # delete target refs/releases absent on source
        force: false   # refs only: overwrite a DIVERGED mirror ref (default off = keep-divergent)
        drafts: false   # releases only: carry unpublished drafts
        only: [<string>]   # releases only: restrict to these tag-sources
        match: <string>   # glob filter on ref/tag name
        assets: <string>   # releases only: "" | "true" | "false" | "link"
      tags:
        scope: <string>   # "current" | "all" (exact expands here)
        prune: false   # delete target refs/releases absent on source
        force: false   # refs only: overwrite a DIVERGED mirror ref (default off = keep-divergent)
        drafts: false   # releases only: carry unpublished drafts
        only: [<string>]   # releases only: restrict to these tag-sources
        match: <string>   # glob filter on ref/tag name
        assets: <string>   # releases only: "" | "true" | "false" | "link"
      releases:
        scope: <string>   # "current" | "all" (exact expands here)
        prune: false   # delete target refs/releases absent on source
        force: false   # refs only: overwrite a DIVERGED mirror ref (default off = keep-divergent)
        drafts: false   # releases only: carry unpublished drafts
        only: [<string>]   # releases only: restrict to these tag-sources
        match: <string>   # glob filter on ref/tag name
        assets: <string>   # releases only: "" | "true" | "false" | "link"

registries

Registries declares OCI registry hosts as an id→registry map.

registries:
  <id>:   # entry key = the unique id
    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

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)
  profiles:   # id→profile map
    <id>:   # entry key = the unique id
      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…

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).

git

Git is the git: cluster and the single source for ref interpretation: named branch patterns (git.branches), tag patterns (git.tags), and versioning rules (git.versioning). Consumers read cfg.Git.Branches / cfg.Git.Tags / cfg.Git.Versioning.{BranchBuilds,NoLineage} directly — no translation layer.

git:
  branches: {}   # Branches maps a matcher name to a regex.
  tags:   # Tags maps a tag-source name to its pattern.
    <id>:   # entry key = the unique id
      pattern: <string>   # Pattern is the regex that identifies tags belonging to this source. e.g., "^v?\\d+\\.\\d+\\.\\d+$" · required
  versioning:   # Versioning holds the derivation rules that consume the patterns above.
    branch_builds:
      <id>:   # entry key = the unique id
        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:
      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…

builds

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

kind: docker

builds:
  <id>:   # entry key = the unique id
    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>:   # entry key = the unique id
    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", "rust", "node", "elixir"… · 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>:   # entry key = the unique id
    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.

publish

Targets defines distribution targets and side-effects. Declared under the publish: key as an id→target map (execution order preserved).

kind: registry

publish:
  <id>:   # entry key = the unique id
    kind: registry   # Kind is the target type. Determines which fields are valid. · required
    registry: [<string>]   # Registry references registries[].id for registry/metadata targets. Accepts a single id (registry…
    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 per series (0/-1/unset = ∞) · 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
      keep_branches: <int>   # keep the N most-recent identity groups per template (bounds retired branches; 0/unset = ∞) · required
      identity: [<string>]   # extra identity vars beyond the {branch}/{env} defaults — partition tags into independent series · required
      protect: [<string>]   # tag patterns that are never deleted, an explicit override · required
    when:   # When specifies routing conditions for this target: a single condition-set, or a list of them (OR…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…

kind: metadata

publish:
  <id>:   # entry key = the unique id
    kind: metadata   # Kind is the target type. Determines which fields are valid. · required
    registry: [<string>]   # Registry references registries[].id for registry/metadata targets. Accepts a single id (registry…
    repos: [<string>]   # Repos names the destination repos[].id for a kind: release target. The repo with role primary is…
    description: [<string>]   # Description is the short project description/tagline. A scalar for kind: registry; kind: metadata…
    readme: <string>   # Readme is the long markdown 'project page' body (registries only: Docker Hub Overview, Harbor Info…
    website: <string>   # Website is the project's external site URL (forges: GitHub, Gitea/Forgejo).
    topics: [<string>]   # Topics are discovery tags (forges: GitHub, GitLab, Gitea). Authored freely; the engine normalizes…
    logo: <string>   # Logo is a path to the project avatar image (project-scoped forges: GitLab, Gitea/Forgejo); synced…
    when:   # When specifies routing conditions for this target: a single condition-set, or a list of them (OR…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…

kind: gitlab-component

publish:
  <id>:   # entry key = the unique id
    kind: gitlab-component   # Kind is the target type. Determines which fields are valid. · 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: a single condition-set, or a list of them (OR…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…

kind: release

publish:
  <id>:   # entry key = the unique id
    kind: release   # Kind is the target type. Determines which fields are valid. · 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). DEPRECATED: prefer `type…
    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 per series (0/-1/unset = ∞) · 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
      keep_branches: <int>   # keep the N most-recent identity groups per template (bounds retired branches; 0/unset = ∞) · required
      identity: [<string>]   # extra identity vars beyond the {branch}/{env} defaults — partition tags into independent series · required
      protect: [<string>]   # tag patterns that are never deleted, an explicit override · required
    when:   # When specifies routing conditions for this target: a single condition-set, or a list of them (OR…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…

kind: binary-archive

publish:
  <id>:   # entry key = the unique id
    kind: binary-archive   # Kind is the target type. Determines which fields are valid. · 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"…
    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: a single condition-set, or a list of them (OR…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…

kind: generic-package

publish:
  <id>:   # entry key = the unique id
    kind: generic-package   # Kind is the target type. Determines which fields are valid. · 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: a single condition-set, or a list of them (OR…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…

kind: pages

publish:
  <id>:   # entry key = the unique id
    kind: pages   # Kind is the target type. Determines which fields are valid. · 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: a single condition-set, or a list of them (OR…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…

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
  render:   # Render controls commit rendering (default DefaultCommitPresentation; a partial render: block…
    preserve_raw_subject: false   # required
    enforce_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…

llms

LLMs is the model endpoint library (llms:): id → { provider, url, model, credentials }, referenced by type: llm stencils via llm: .

llms:
  <id>:   # entry key = the unique id
    provider: <string>   # ollama (openai | anthropic | claude-agent reserved) · required
    url: <string>   # ollama: server base URL
    model: <string>   # model name/tag
    credentials: <string>   # env prefix for hosted providers

stencils

Stencils is the shared audience-text library: id → reusable markdown element with {…} variable fill, embeddable as {id} anywhere SF composes text (scribe file regions, narrate, release bodies). Presence-neutral (a shared library, not a phase). Consumers differ only by destination.

kind: badge

stencils:
  <id>:   # entry key = the unique id
    type: <string>   # SOURCE × RENDER.
    render: <string>   # form: badge (default) | shield | image | table | list | kv | versions | raw
    label: <string>   # ── inline badge / shield areas ──
    message: <string>   # right value (templates)
    color: <string>   # hex or "auto"
    font: <string>   # badge font override
    font_size: <int>   # badge font size override
    output: <string>   # SVG output path (badge generation)
    link: <string>   # clickable URL
    logo: <string>   # shields.io logo / props logo
    logo_color: <string>
    label_color: <string>

kind: shield

stencils:
  <id>:   # entry key = the unique id
    type: <string>   # SOURCE × RENDER.
    render: <string>   # form: badge (default) | shield | image | table | list | kv | versions | raw
    shield: <string>   # shields.io path (render: shield)
    link: <string>   # clickable URL

kind: text

stencils:
  <id>:   # entry key = the unique id
    type: <string>   # SOURCE × RENDER.

kind: component

stencils:
  <id>:   # entry key = the unique id
    type: <string>   # SOURCE × RENDER.
    spec: <string>   # ── component ──

kind: include

stencils:
  <id>:   # entry key = the unique id
    type: <string>   # SOURCE × RENDER.
    path: <string>   # ── include ──

kind: contents

stencils:
  <id>:   # entry key = the unique id
    type: <string>   # SOURCE × RENDER.
    build: <string>   # ── contents (build manifest) / ci (run-state producers) ──
    source: <string>
    section: <string>
    columns: [<string>]   # contents renderer form lives on the RENDER axis (render:), not a separate renderer: key — one…
    output_file: <string>
    wrap: <string>
    summary: <string>
    style: <string>
    params: {}   # ── props (github-*, goreportcard, …) ──

scribe

Scribe places rendered stencils into repository files and commits them: files: (placement regions whose bodies reference stencils by {id}) + commit:. Presence-enabled (files/commit gate the stage).

scribe:
  store: <string>   # dir for rendered file assets (default .stagefreight/scribe); path = {store}/{id}.svg
  files:   # id → placement region referencing stencils
    <id>:   # entry key = the unique id
      file: <string>   # required
      link_base: <string>
      between: <value>
      inline: false   # items sugar: render side-by-side
      items: [<string>]   # stencil ids (+ "br"); sugar for a body
      body: <string>   # freeform markdown with {id} embeds
  commit:   # scribe's own auto-commit action
    type: <string>
    message: <string>
    add: [<string>]
    push: false
    skip_ci: false
    run_from:
      allow: [<string>]   # permitted origins: "primary"
      mismatch: <string>   # "read-only" (default), "exit", "ignore"

notifications

Notifications sends a message when a run finishes: id → { provider, on, subject, body, … }. Flat, one entry per notification. subject/body accept {…} embeds; an omitted body defaults to the run's apex summary. Dispatched by the narrate phase.

notifications:
  <id>:   # entry key = the unique id
    provider: <string>   # ntfy | webhook · required
    url: <string>   # Transport. Credentials follows the shipped env-prefix convention (credentials: NTFY → NTFY_TOKEN…
    credentials: <string>
    subject: <string>   # Message — freeform stencil bodies.
    body: <string>
    when:   # When gates dispatch: outcomes: (success | failure | warning) composing with…
      - 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…
        forges: [<string>]   # Forges restricts this target to specific CI forges by provider name (github, gitlab, gitea…
        outcomes: [<string>]   # Outcomes gates on the RUN outcome (success | failure | warning) — the notification dimension of…
    max_length: <int>   # MaxLength hard-caps the rendered body in bytes (ntfy's default server limit is 4096). Trimming…
    priority: <string>   # ntfy knobs — the full header vocabulary.
    tags: [<string>]   # emoji tags (comma-joined into the Tags header)
    click: <string>   # tap-through URL (stencil body; default {pipeline_url})
    attach: <string>   # attachment URL
    actions: <string>   # ntfy actions spec string
    markdown: false   # render body as markdown
    email: <string>   # forward to email address

narrate

Narrate is the stdout storytelling surface: announces: lists stencil ids rendered as structured-output cards at the end of the run (default: the built-in summary).

narrate:
  announces: [<string>]

test

test:
  preset: <string>
  enabled: false   # required
  auto: false   # nil ⇒ true
  suites:
    <id>:   # entry key = the unique id
      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: false   # SecuritySummary attaches the security summary to the release. The summary's location is… · required
  registry_links: false   # required
  catalog_links: false   # required
  render:   # Render controls release rendering (default DefaultReleasePresentation; a partial render: block…
    max_entries: <int>   # required
    group_by_type: false   # required
    style: <string>   # concise | explanatory | technical · required
    include_release_visible_only: 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

ansible

Ansible defines the ansible host-convergence subsystem. Presence-gated (any converge playbook activates it) and independent of lifecycle.mode.

ansible:
  preset: <string>
  backend: <string>   # Backend selects the host-convergence backend. Default: "ansible". · required
  image: <string>   # Image is the execution image the playbooks (and ansible-lint) run in — the ansible runtime… · required
  inventory: <string>   # Inventory is the repo-relative ansible inventory file. · required
  ssh:   # SSH is the shared connection identity used by every play. · required
    user: <string>   # User is the remote login user on the managed hosts. · required
    credentials: <string>   # Credentials is the env-prefix name the SSH key material is read from. · required
    known_hosts: <string>   # KnownHosts is the repo-relative known_hosts file holding the managed hosts' public keys. Host-key… · required
  playbooks:   # Playbooks is the play library: an order-preserving id → entry map. Entries with converge: true… · required
    <id>:   # entry key = the unique id
      path: <string>   # Path is the repo-relative playbook file. · required
      groups: [<string>]   # Groups are the inventory groups this play targets (rendered as --limit). · required
      converge: false   # Converge marks the play as desired-state: it runs on every perform reconcile. False declares a… · 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.
    registry: <string>   # Registry references a registries[].id. Its URL + default_path locate the cache.
    path: <string>   # Path is appended to the registry URL: <registry-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

tagging

Tag holds workflow defaults for the tag planner.

tagging:
  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
  render:   # Render controls tag change-log rendering (default DefaultTagPresentation; a partial render: block…
    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

toolchains

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

Name YAML Key Type Required Default Description
toolchains toolchains map[string]object No — Toolchains defines operator control over external tool resolution. Version pins, future retention policy, future trust settings.