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.
Each key's generated reference follows.
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
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…
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>]
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…
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"
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
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:
desired: {} # Desired declares intended tool constraints. Authoritative — not a hint. If a desired constraint…
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