Policy

The cross-cutting rules that shape when and how the pipeline acts — event routing, version identity, release/security behavior, commit and tag authoring, toolchain pins, and publish manifests. These are the knobs you reach for once the basics work.

A few of these keys carry behavior worth explaining before the generated field reference; the rest are documented inline in the reference blocks below.

Git — ref interpretation & versioning

git: interprets the current ref into named branch and tag patterns and the versions they imply. git.branches and git.tags define named patterns (main, stable, …) that targets reference from when.branches / when.git_tags, so routing lives in one place; git.versioning derives {version} from those patterns (base tag source + format). The matching syntax itself — regex, negation, literal — is shared with every conditional field and documented under Concepts → Patterns & conditions.

Security scanning

security: scans built images for vulnerabilities, generates SBOMs, and embeds the results in release notes. Both scanners default on but still require their binary in PATH.

security:
  enabled: true
  scanners:
    trivy: true                  # container image scan (default: true)
    grype: true                  # container image scan, Anchore (default: true)
  sbom: true                     # generate a CycloneDX SBOM via Syft
  fail_on_critical: false        # exit non-zero on critical vulns
  output_dir: ".stagefreight/security"
  release_detail: counts         # default detail level in release notes

Detail levels control how much lands in release notes: none, counts (e.g. "0 critical, 2 high"), detailed (counts + affected packages), or full (a table with CVE IDs, severity, and descriptions). release_detail_rules override the level per tag/branch (top-down, first match wins — the same condition syntax as everywhere else):

  release_detail_rules:
    - tag: "^v\\d+\\.\\d+\\.\\d+$"    # stable releases → full
      detail: "full"
    - branch: "^main$"                # main → detailed
      detail: "detailed"
    - detail: "counts"                # catch-all

Precedence: CLI --security-detail > first matching rule > release_detail.

A scan writes results.json (Trivy JSON), results.sarif (for GitLab/GitHub security dashboards), sbom.json (CycloneDX, when sbom: true), and summary.md into output_dir. These become release assets — see Publish → Release.

Reference

Each key's generated reference follows.

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.
  submodules: false   # Submodules requests that CI check out submodules. A pipeline that clones without them leaves the…
  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…

---

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
  forge: [<string>]   # Forge names the forge whose CI skeleton this repo runs on, and therefore which pipeline file…
  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>]

---

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

---

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

---

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 —…
  outdated:   # Outdated gates on how far a dependency has fallen behind — an update-MAGNITUDE policy, not a…
    at: <string>   # At is the smallest magnitude that trips the gate: "major" | "minor" | "patch", or "off". Empty…
    action: <string>   # Action is what a tripped gate does: "warn" (default) or "error". Warn is the default deliberately…
  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…

---

release

Release holds configuration for the release subsystem.

release:
  preset: <string>
  enabled: false   # required
  required: false   # failure is hard pipeline fail (default: false)
  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"

---

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…
  exceptions:   # Exceptions are reviewed, on-record decisions to excuse specific advisories from the fail_on gate…
    - id: <string>   # ID is the advisory this excepts (CVE / GHSA), matched case-insensitively. Required. · required
      reason: <string>   # Reason is why the advisory is accepted or not applicable. Required — there is no anonymous… · required
      expires: <string>   # Expires optionally lapses the exception on a date (YYYY-MM-DD). Past its expiry the advisory gates…
      package: <string>   # Package optionally scopes the exception to a single package name, so a later, unrelated advisory…
  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
  release_detail_max_rows: <int>   # ReleaseDetailMaxRows bounds how many vulnerability rows the "full" detail level writes into release…
  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

---

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

---

toolchains

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

toolchains:
  want: {}   # Want is the tool→constraint map — the versions the operator WANTS (constraints, not necessarily…
  retention:   # Retention governs how many resolved versions of each tool are RETAINED on the runner (keep_last…
    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
    max_age: <string>   # keep items newer than this ("14d", "72h"); additive like keep_* — alone it means "only the recent… · 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
    refs:   # scoped overrides: a different policy for items matching a pattern (first match wins; unset fields… · required
      - match: <string>   # pattern (same syntax as protect/templates) · required
        keep_last: <int>   # required
        keep_daily: <int>   # required
        keep_weekly: <int>   # required
        keep_monthly: <int>   # required
        keep_yearly: <int>   # required
        max_age: <string>   # required

---

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

---