Lifecycle Modes

The single most architecturally significant choice: lifecycle.mode selects the phase graph the pipeline runs — build container images (image, the default), validate GitOps manifests (gitops), reconcile governance (governance), or drive the docker lifecycle (docker). Each mode has its own config section.

Real examples

dungeon runs mode: gitops; MaintenancePolicy runs mode: governance — see Quick Start.

lifecycle

Selects the repository lifecycle mode — the phase graph the pipeline runs. The single most architecturally significant config choice: it determines whether the repo builds container images, validates GitOps manifests, or reconciles governance. When omitted, the lifecycle defaults to image.

lifecycle:
  preset: <string>   # Preset references an external lifecycle fragment to inherit (the generic preset: fragment-include…
  mode: <string>   # Mode selects the phase graph. Empty defaults to image. image — build → review → publish image… · required

Phase applicability is mode-derived: the review and publish phases do work only in image mode; gitops, governance, and docker mark them not_applicable. Capability requirements differ per mode (e.g. gitops requires Reconcile + ImpactAnalysis, plus ClusterAuth when gitops.cluster is set); the lifecycle backend is checked against them at plan time.

---

gitops

GitOps defines configuration for the gitops lifecycle mode.

gitops:
  preset: <string>
  backend: <string>   # Backend selects the GitOps reconciliation backend (e.g. "flux", "argo"). · required
  cluster:   # Cluster defines the target Kubernetes cluster. · required
    name: <string>   # required
    server: <string>   # required
    exposure:   # required
      rules:   # required
        - level: <string>   # internet | intranet | cluster · required
          endpoints: [<string>]   # ip:port (highest precedence) · required
          gateways: [<string>]   # required
          cidrs: [<string>]   # required
          ports: [...]   # AND with CIDRs (empty = any port) · required
          service_types: [<string>]   # ClusterIP | NodePort | LoadBalancer · required
  oidc:   # OIDC defines authentication configuration for the cluster. · required
    audience: <string>   # required

---

governance

Governance defines configuration for the governance lifecycle mode. Only valid in the control repo (lifecycle.mode: governance).

governance:
  clusters:   # required
    - id: <string>   # required
      targets:   # required
        repos: [<string>]
        groups:
          - id: <string>
            repos: [<string>]   # required
        credentials: <string>   # env var prefix for forge auth
      stagefreight: {}   # required

---

docker

Docker defines configuration for the docker lifecycle mode.

docker:
  preset: <string>
  backend: <string>   # Backend selects the Docker execution engine (e.g. "compose"). · required
  targets:   # Targets defines how reconciliation targets are resolved. · required
    source: <string>   # Source is the inventory adapter (e.g. "ansible"). · required
    inventory: <string>   # Inventory is the path to the inventory file (relative to repo root). · required
    selector:   # Selector declares which hosts from inventory are eligible. · required
      groups: [<string>]   # required
  iac:   # IaC defines the Infrastructure as Code directory layout. · required
    path: <string>   # Path is the IaC directory relative to repo root (default: "docker-compose"). · required
  secrets:   # Secrets defines the secrets decryption provider. · required
    provider: <string>   # Provider selects the secrets backend (e.g. "sops", "vault", "infisical"). · required
  drift:   # Drift defines drift detection and reconciliation policy. · required
    tier2_action: <string>   # report | reconcile (default: report) · required
    orphan_action: <string>   # report | down | prune (default: report) · required
    orphan_threshold: <int>   # block if more than N orphans (default: 5) · required
    prune_requires_confirmation: false   # require --force for prune (default: true) · required

---