Identity & Connectivity¶

Who you are and what you talk to: template variables, the git hosts (forges) and projects (repos) StageFreight pushes to, and the container registries it authenticates against.

The reference for each key is generated from the config source below.

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.

forges¶

Forges declares git hosts. Each entry is a host identity (provider, URL, credentials).

forges:
  - id: <string>   # unique identifier (e.g., "prplanit-gitlab") · required
    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 on forges. References forges by id. Has role (primary/mirror).

repos:
  - id: <string>   # unique identifier · required
    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
      git: false   # Git enables authoritative mirror replication via git push --mirror. All refs, branches, tags…
      releases: false   # Releases enables forge-native release projection (notes, assets, links). Runs after git mirror…
      docs: false   # Docs enables README/doc file projection via forge commit API. Mutually exclusive with Git (docs…

registries¶

Registries declares OCI registry hosts. Referenced by targets.

registries:
  - id: <string>   # unique identifier (e.g., "dockerhub") · required
    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}")