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.

version

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

Name	YAML Key	Type	Required	Default	Description
`version`	`version`	int	Yes	—	int value

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	—	map[string]string value

Example:

vars:
  org: prplanit
  repo: stagefreight

defaults

sources

Build source configuration. Defines where source code lives and how to derive link/raw URLs.

Name	YAML Key	Type	Required	Default	Description
`kind`	`primary.kind`	string	Yes	git	Source type.
`worktree`	`primary.worktree`	string	Yes	"."	Path to working tree.
`url`	`primary.url`	string	Yes	—	Repository URL. Enables deterministic link_base/raw_base derivation.
`default_branch`	`primary.default_branch`	string	Yes	—	Default branch name. Used with URL for raw_base derivation.

Example:

sources:
  primary:
    kind: git
    worktree: "."
    url: "https://github.com/myorg/myrepo"
    default_branch: "main"

policies

Named regex patterns for git tag and branch matching. Referenced by target when conditions (e.g., git_tags: [stable]).

Name	YAML Key	Type	Required	Default	Description
`git_tags`	`git_tags`	map[string]string	Yes	—	map[string]string value
`branches`	`branches`	map[string]string	Yes	—	map[string]string value

Example:

policies:
  git_tags:
    stable: "^v?\\d+\\.\\d+\\.\\d+$"
    prerelease: "^v?\\d+\\.\\d+\\.\\d+-.+"
  branches:
    main: "^main$"

builds

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

Name	YAML Key	Type	Required	Default	Description
`id`	`id`	string	Yes	—	Unique identifier for this build, referenced by targets.
`kind`	`kind`	string	Yes	—	Build type. Determines which fields are valid.
`select_tags`	`select_tags`	[]string	No	—	Tags for CLI filtering via `--select`.
`build_mode`	`build_mode`	string	No	(standard)	Build execution strategy.
`dockerfile`	`dockerfile`	string	No	auto-detected	Path to the Dockerfile.
`context`	`context`	string	No	"."	Docker build context path.
`target`	`target`	string	No	—	Multi-stage build `--target` stage name.
`platforms`	`platforms`	[]string	No	current OS/arch	Target platforms for multi-arch builds.
`build_args`	`build_args`	map[string]string	No	—	Key-value pairs passed as `--build-arg`. Supports template variables.
`paths`	`cache.watch.paths`	[]string	Yes	—	Glob patterns for files to watch for changes.
`invalidates`	`cache.watch.invalidates`	[]string	Yes	—	Build stage names invalidated when watched files change.
`auto_detect`	`cache.auto_detect`	bool	Yes	true	Auto-detect cache-relevant files from Dockerfile COPY/ADD instructions.

kind allowed values: docker

build_mode allowed values: (standard), crucible

Crucible mode performs a self-proving rebuild to verify build reproducibility.

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

Example:

builds:
  - id: myapp
    kind: docker
    platforms: [linux/amd64, linux/arm64]

targets

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

Name	YAML Key	Type	Required	Default	Description
`id`	`id`	string	Yes	—	Unique identifier for this target (logging, status, enable/disable).
`kind`	`kind`	string	Yes	—	Target type. Determines which fields are valid.
`build`	`build`	string	No	—	References a `builds[].id`. Required for `kind: registry`.
`branches`	`when.branches`	[]string	No	—	Branch filters. Each entry is a policy name or inline regex.
`git_tags`	`when.git_tags`	[]string	No	—	Git tag filters. Each entry is a policy name or inline regex.
`events`	`when.events`	[]string	No	—	CI event type filters.
`select_tags`	`select_tags`	[]string	No	—	[]string value
`url`	`url`	string	No	—	Registry or forge hostname.
`provider`	`provider`	string	No	—	Vendor type for auth and API behavior. Auto-detected from URL if omitted on registry/docker-readme targets.
`path`	`path`	string	No	—	Image path within the registry.
`credentials`	`credentials`	string	No	—	Env var prefix for authentication. Resolution: try `{PREFIX}_TOKEN` first, else `{PREFIX}_USER` + `{PREFIX}_PASS`.
`description`	`description`	string	No	—	string value
`keep_last`	`retention.keep_last`	int	Yes	—	Keep the N most recent tags/releases.
`keep_daily`	`retention.keep_daily`	int	Yes	—	Keep one per day for the last N days.
`keep_weekly`	`retention.keep_weekly`	int	Yes	—	Keep one per week for the last N weeks.
`keep_monthly`	`retention.keep_monthly`	int	Yes	—	Keep one per month for the last N months.
`keep_yearly`	`retention.keep_yearly`	int	Yes	—	Keep one per year for the last N years.
`protect`	`retention.protect`	[]string	Yes	—	Tag patterns that are never deleted.
`tags`	`tags`	[]string	No	—	Tag templates resolved against version info. `kind: registry` only.
`file`	`file`	string	No	—	Path to the README file. `kind: docker-readme` only.
`link_base`	`link_base`	string	No	—	Base URL for relative link rewriting. `kind: docker-readme` only.
`spec_files`	`spec_files`	[]string	No	—	Component spec file paths. `kind: gitlab-component` only.
`catalog`	`catalog`	bool	No	—	Enable GitLab Catalog registration. `kind: gitlab-component` only.
`aliases`	`aliases`	[]string	No	—	Rolling git tag aliases. `kind: release` only.
`project_id`	`project_id`	string	No	—	Project identifier (`owner/repo` or numeric ID). `kind: release`, remote targets only.
`sync_release`	`sync_release`	bool	No	—	Sync release notes + tags to a remote forge. `kind: release`, remote targets only.
`sync_assets`	`sync_assets`	bool	No	—	Sync scan artifacts to a remote forge. `kind: release`, remote targets only.

kind allowed values: registry, docker-readme, gitlab-component, release

when.events allowed values: push, tag, release, schedule, manual, pull_request, merge_request

provider allowed values: docker, ghcr, gitlab, jfrog, harbor, quay, gitea, forgejo, ecr, gar, acr, nexus, generic, github

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

Example:

targets:
  - id: dockerhub-stable
    kind: registry
    build: myapp
    url: docker.io
    path: myorg/myapp
    tags: ["{version}", "latest"]
    when: { git_tags: [stable], events: [tag] }
    credentials: DOCKER

narrator

Content composition for file targets. Composes badges, shields, text, includes, and components into managed  sections in any file.

Name	YAML Key	Type	Required	Default	Description
`file`	`file`	string	Yes	—	Path to the target file.
`link_base`	`link_base`	string	No	—	Base URL for relative link rewriting. `raw_base` is auto-derived from this.
`id`	`items.id`	string	Yes	—	Item identifier, unique within file.
`kind`	`items.kind`	string	Yes	—	Item type. Determines which fields are valid.
`between`	`items.placement.between`	array	No	—	Two-element array: `[start_marker, end_marker]`. Content is placed between these markers.
`after`	`items.placement.after`	string	No	—	string value
`before`	`items.placement.before`	string	No	—	string value
`heading`	`items.placement.heading`	string	No	—	string value
`mode`	`items.placement.mode`	string	No	replace	How content is placed relative to markers.
`inline`	`items.placement.inline`	bool	No	false	Render items side-by-side (space-joined) when true. Default: block (newline-joined).
`text`	`items.text`	string	No	—	Badge label (left side text). `kind: badge` only.
`value`	`items.value`	string	No	—	Badge value (right side text, supports templates). `kind: badge` only.
`color`	`items.color`	string	No	—	Badge color as hex or `auto` (status-driven). `kind: badge` only.
`font`	`items.font`	string	No	—	string value
`font_size`	`items.font_size`	int	No	—	int value
`output`	`items.output`	string	No	—	SVG output path for badge generation. `kind: badge` only.
`link`	`items.link`	string	No	—	Clickable URL. `kind: badge` and `kind: shield`.
`shield`	`items.shield`	string	No	—	Shields.io path (appended to `https://img.shields.io/`). `kind: shield` only.
`content`	`items.content`	string	No	—	Raw text/markdown content. Supports template variables. `kind: text` only.
`spec`	`items.spec`	string	No	—	Component spec file path. `kind: component` only.
`path`	`items.path`	string	No	—	File path to include verbatim. `kind: include` only.
`source`	`items.source`	string	No	—	string value
`section`	`items.section`	string	No	—	string value
`renderer`	`items.renderer`	string	No	—	string value
`columns`	`items.columns`	[]string	No	—	[]string value
`output_file`	`items.output_file`	string	No	—	string value
`type`	`items.type`	string	No	—	string value
`params`	`items.params`	map[string]string	No	—	map[string]string value
`label`	`items.label`	string	No	—	string value
`style`	`items.style`	string	No	—	string value
`logo`	`items.logo`	string	No	—	string value

items.kind allowed values: badge, shield, text, component, break, include

items.placement.mode allowed values: replace, append, prepend, above, below

Example:

narrator:
  - file: "README.md"
    link_base: "https://github.com/myorg/myrepo/blob/main"
    items:
      - id: badge.release
        kind: badge
        placement:
          between: ["<!-- sf:badges:start -->", "<!-- sf:badges:end -->"]
          mode: replace
          inline: true
        text: release
        output: ".stagefreight/badges/release.svg"

lint

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

Name	YAML Key	Type	Required	Default	Description
`level`	`level`	string	Yes	changed	Scan mode. `changed` scans only modified files; `full` scans everything.
`cache_dir`	`cache_dir`	string	Yes	$XDG_CACHE_HOME/stagefreight//lint	Override cache directory.
`target_branch`	`target_branch`	string	Yes	—	Target branch for diff-based scanning.
`exclude`	`exclude`	[]string	Yes	—	Glob patterns to exclude from lint scanning.
`modules`	`modules`	map[string]object	Yes	—	Per-module configuration. Keys: tabs, secrets, conflicts, filesize, linecount, unicode, yaml, lineendings, freshness.

level allowed values: changed, full

Example:

lint:
  level: changed
  modules:
    secrets:
      enabled: true
    freshness:
      enabled: true
      options:
        cache_ttl: 300

security

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

Name	YAML Key	Type	Required	Default	Description
`enabled`	`enabled`	bool	Yes	true	Run vulnerability scanning.
`trivy`	`scanners.trivy`	bool	No	true	Run Trivy image scan.
`grype`	`scanners.grype`	bool	No	true	Run Grype image scan.
`sbom`	`sbom`	bool	Yes	true	Generate SBOM artifacts via Syft.
`fail_on_critical`	`fail_on_critical`	bool	Yes	false	Fail the pipeline if critical vulnerabilities are found.
`output`	`output`	string	Yes	.stagefreight/security	Directory for scan artifacts (JSON, SARIF, SBOM, summary).
`release_detail`	`release_detail`	string	Yes	counts	Default detail level for security info in release notes.
`tag`	`release_detail_rules.tag`	string	No	—	Git tag pattern to match. Prefix with `!` to negate.
`branch`	`release_detail_rules.branch`	string	No	—	Branch pattern to match. Prefix with `!` to negate.
`detail`	`release_detail_rules.detail`	string	Yes	—	Detail level when this rule matches.
`overwhelm_message`	`overwhelm_message`	[]string	Yes	["…maybe start here:"]	Message lines shown when >1000 vulnerabilities are found.
`overwhelm_link`	`overwhelm_link`	string	Yes	—	URL appended after overwhelm message. Empty string disables.

release_detail allowed values: none, counts, detailed, full

release_detail_rules.detail allowed values: none, counts, detailed, full

Example:

security:
  enabled: true
  scanners:
    trivy: true
    grype: true
  sbom: true
  release_detail: counts

commit

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

Name	YAML Key	Type	Required	Default	Description
`default_type`	`default_type`	string	No	chore	Default commit type when --type is omitted.
`default_scope`	`default_scope`	string	No	—	Default commit scope when --scope is omitted.
`skip_ci`	`skip_ci`	bool	No	false	Append `[skip ci]` to commit subjects by default.
`push`	`push`	bool	No	false	Push after committing by default.
`conventional`	`conventional`	bool	Yes	true	Use conventional commit format (`type(scope): summary`).
`backend`	`backend`	string	No	git	Commit execution backend.
`key`	`types.key`	string	Yes	—	Type identifier used in `--type` flag. Must match `^[a-z][a-z0-9_-]*$`.
`label`	`types.label`	string	Yes	—	Human-readable label for documentation and error messages.
`alias_for`	`types.alias_for`	string	No	—	Resolve this type to another type key. No alias chains allowed.
`force_bang`	`types.force_bang`	bool	No	false	Force breaking change indicator (`!`) when this type is used.

backend allowed values: git, dry-run

Example:

commit:
  default_type: docs
  conventional: true
  backend: git
  skip_ci: false
  push: false
  types:
    - key: feat
      label: Feature
    - key: breaking
      label: Breaking
      force_bang: true

dependency

Name	YAML Key	Type	Required	Default	Description
`enabled`	`enabled`	bool	Yes	—	bool value
`output`	`output`	string	Yes	—	string value
`go_modules`	`scope.go_modules`	bool	Yes	—	bool value
`dockerfile_env`	`scope.dockerfile_env`	bool	Yes	—	bool value
`enabled`	`commit.enabled`	bool	Yes	—	bool value
`type`	`commit.type`	string	Yes	—	string value
`message`	`commit.message`	string	Yes	—	string value
`push`	`commit.push`	bool	Yes	—	bool value
`skip_ci`	`commit.skip_ci`	bool	Yes	—	bool value
`handoff`	`ci.handoff`	string	Yes	—	string value

docs

Name	YAML Key	Type	Required	Default	Description
`enabled`	`enabled`	bool	Yes	—	bool value
`badges`	`generators.badges`	bool	Yes	—	bool value
`reference_docs`	`generators.reference_docs`	bool	Yes	—	bool value
`narrator`	`generators.narrator`	bool	Yes	—	bool value
`docker_readme`	`generators.docker_readme`	bool	Yes	—	bool value
`enabled`	`commit.enabled`	bool	Yes	—	bool value
`type`	`commit.type`	string	Yes	—	string value
`message`	`commit.message`	string	Yes	—	string value
`add`	`commit.add`	[]string	Yes	—	[]string value
`push`	`commit.push`	bool	Yes	—	bool value
`skip_ci`	`commit.skip_ci`	bool	Yes	—	bool value

manifest

Name	YAML Key	Type	Required	Default	Description
`enabled`	`enabled`	bool	Yes	—	bool value
`mode`	`mode`	string	No	—	string value
`output_dir`	`output_dir`	string	No	—	string value

release

Name	YAML Key	Type	Required	Default	Description
`enabled`	`enabled`	bool	Yes	—	bool value
`security_summary`	`security_summary`	string	Yes	—	string value
`registry_links`	`registry_links`	bool	Yes	—	bool value
`catalog_links`	`catalog_links`	bool	Yes	—	bool value

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

StageFreight — Config Reference

Config Sections

version

vars

defaults

sources

policies

builds

targets

narrator

lint

security

commit

dependency

docs

manifest

release

FilesExpand file tree

Config.md

Latest commit

History

Config.md

File metadata and controls

StageFreight — Config Reference

Config Sections

version

vars

defaults

sources

policies

builds

targets

narrator

lint

security

commit

dependency

docs

manifest

release