Promotion and reconciliation

Promotion chooses what an environment should run next. Reconciliation repeatedly makes the environment match what Git already says it should run. Resilience Gate assigns those responsibilities to different controllers so a running workload can be traced back to a deliberate candidate selection and rendered commit.

The two control loops

Kargo discovers application image digests and chart-source revisions, groups them into Freight, selects a candidate for a Stage, renders the chart, and commits the result to that environment’s output branch. Argo CD watches the output branch and reconciles its manifests into Kubernetes. Kargo asks Argo CD to sync the exact rendered commit; Argo CD remains the component applying desired workload state.

Enlarge diagram: Kargo and Argo CD ownership boundaries · Version-controlled diagram source

Kargo owns candidate selection and rendered output; Argo CD owns reconciliation. Verification supplies eligibility evidence after the deployment handoff.

The ApplicationSet registers three Applications, each tracking env/<environment> at repository path .. Its authorized-stage annotation grants the matching Kargo Stage permission to request a sync. Automated pruning and self-healing belong to Argo CD’s sync policy. They repair drift against Git; they do not make an unverified candidate eligible for another Stage.

Sources and outputs have different owners

The Warehouse’s Git subscription watches main, limited to helm/url-shortener. The env/* branches are rendered outputs and are deliberately excluded as Freight sources. Feeding those outputs back into discovery would blur the boundary between a chart change and the result of rendering a chart.

Each Stage template checks out the Freight source commit into ./src and the target branch into ./out. It writes the selected image repository and digest into the source checkout’s environment values, clears the output directory, runs Helm, commits the output, pushes the environment branch, and requests the resulting commit through argocd-update.

The source revision answers “which chart and values were used?” The rendered revision answers “which desired state was reconciled?” Both are needed to inspect a release. Editing controller-owned output branches as an ordinary source change breaks that explanation and can race the next promotion.

Verification changes eligibility

The Project policy allows automatic dev promotion. Staging and prod promotion remain manual. Dev accepts Freight directly from the Warehouse and runs readiness verification. Staging’s normal source is Freight verified in dev; after a manually requested staging promotion it runs readiness plus the chaos gate. Prod’s normal source is Freight verified in staging; after an explicit prod-like promotion it runs readiness and liveness.

A successful staging verification grants normal downstream eligibility. It does not initiate automatic prod promotion. Conversely, a separate manual Freight approval is an override, not proof that upstream verification succeeded. The promotion contract documents this distinction, and prod and staging tests check the source-stage and manual-policy configuration.

Where progress can stop

These loops expose different failure layers:

Layer	Example obstruction	What success at a prior layer does not prove
Discovery	Registry access or chart-source retrieval fails	A successful CI upload does not prove Kargo can read it.
Promotion/render	Git credentials, Helm rendering, or output push fails	Freight selection does not prove usable manifests exist.
Reconciliation	Image pull, missing Secret, or unschedulable Pod	A pushed render does not prove running workloads.
Verification	Readiness failure, unavailable traffic, invalid telemetry, or bad score	Argo CD health does not prove fault tolerance.
Downstream action	No explicit prod promotion requested	Staging verification does not mean prod was changed.

The bootstrap GitOps phase orders credentials, policy, analyses, Stages, and Argo CD destinations before Warehouse discovery. Registering the destinations first avoids initiating a chain whose reconciliation targets do not yet exist. The phase does not itself promote Freight, force synchronization, or run paid load.

The topology limits the claim

The environments use separate namespaces in the same owned testnet cluster. They do not form independent clusters, regions, or administrative blast-radius domains. The label prod means a production-like testnet profile with three application replicas. It does not establish public production readiness or high availability for its single-instance PostgreSQL and Redis dependencies.

This ownership split makes diagnosis and provenance clearer, at the cost of more handoffs to observe. A release claim needs the selected Freight, output commit, Argo CD readback, verification result, and cleanup evidence. One controller’s green badge cannot answer for all of them.

Read the release journey for the complete handoff sequence and delivery system design for component interfaces and failure handling.