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 as an id→forge map (provider, URL, credentials).

forges:
  <id>:   # entry key = the unique id
    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 as an id→repo map. References forges by id. Has role.

repos:
  <id>:   # entry key = the unique id
    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
      branches:
        scope: <string>   # "current" | "all" (exact expands here)
        prune: false   # delete target refs/releases absent on source
        force: false   # refs only: overwrite a DIVERGED mirror ref (default off = keep-divergent)
        drafts: false   # releases only: carry unpublished drafts
        only: [<string>]   # releases only: restrict to these tag-sources
        match: <string>   # glob filter on ref/tag name
        assets: <string>   # releases only: "" | "true" | "false" | "link"
      tags:
        scope: <string>   # "current" | "all" (exact expands here)
        prune: false   # delete target refs/releases absent on source
        force: false   # refs only: overwrite a DIVERGED mirror ref (default off = keep-divergent)
        drafts: false   # releases only: carry unpublished drafts
        only: [<string>]   # releases only: restrict to these tag-sources
        match: <string>   # glob filter on ref/tag name
        assets: <string>   # releases only: "" | "true" | "false" | "link"
      releases:
        scope: <string>   # "current" | "all" (exact expands here)
        prune: false   # delete target refs/releases absent on source
        force: false   # refs only: overwrite a DIVERGED mirror ref (default off = keep-divergent)
        drafts: false   # releases only: carry unpublished drafts
        only: [<string>]   # releases only: restrict to these tag-sources
        match: <string>   # glob filter on ref/tag name
        assets: <string>   # releases only: "" | "true" | "false" | "link"

registries¶

Registries declares OCI registry hosts as an id→registry map.

registries:
  <id>:   # entry key = the unique id
    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}")

`llms:` — model endpoints¶

llms: is an endpoint library, a sibling of forges: and registries:: each entry names a model backend (provider, URL, model, credentials) that AI stencils reference by id — so endpoints and credentials never leak into composition. provider: ollama ships first; openai / anthropic / claude-agent slot in behind the same shape. See Stencils & Scribe for the type: llm stencil that consumes these, and Narration & Notifications for dispatching AI output.

llms¶

LLMs is the model endpoint library (llms:): id → { provider, url, model, credentials }, referenced by type: llm stencils via llm: .

llms:
  <id>:   # entry key = the unique id
    provider: <string>   # ollama (openai | anthropic | claude-agent reserved) · required
    url: <string>   # ollama: server base URL
    model: <string>   # model name/tag
    credentials: <string>   # env prefix for hosted providers