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.
Matchers — named routing¶
matchers: defines named patterns (stable, edge, …) that targets reference from
when.git_tags / when.branches, so routing lives in one place. The matching syntax
itself — regex, negation, literal, first-match-wins — 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 Targets → Release.
Reference¶
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