A progression graph maps the environments an artifact can reach and the governed paths between them. CI produces the artifact; Kargo decides which version is eligible to advance into each environment; a GitOps agent reconciles the resulting desired state. The graph is not a build pipeline or a replacement for Git as the source of truth. section 1.2
Each environment is a Kargo Stage. A Stage declares where it requests Freight from, the conditions for promotion, and the steps to run when promotion occurs. Freight is an immutable record of an artifact set; a Promotion records one advancement into a Stage and its outcome. Stages and their related resources live within a Project’s namespace and RBAC boundary. section 3.2.3 section 3.2
From discovery to staging
A Warehouse discovers an image version and produces Freight. A dev Stage requests Freight directly from that Warehouse with `sources.direct: true`. A staging Stage instead requests it from dev with `sources.stages: [dev]`, making Freight eligible for staging only after verification in dev. Promotion steps can update the environment’s image tag in a GitOps repository and then request an Argo CD update. If advancement stalls, inspect the affected resource with `kubectl describe`; stage ordering is one possible cause. section 3.2.3 section 3.7
A graph need not be a line. After dev, smoke and performance testing can run in parallel, with advancement downstream waiting for both. Regional pre-production and production environments can then progress independently. Ask which environments contain, have verified, or have approved a version—not merely whether it is “in production.” Disaster-recovery environments kept in sync with production are not necessarily separate promotion targets. section 2.3 section 2.5
Figure 2.3 Lumen Retail’s environment graph for one service. A version built by CI moves to dev, then into smoke and perf in parallel, and has to pass both before either regional pre-prod environment will take it. Each pre-prod feeds the production regions it stands in for, and each production region is mirrored by a disaster-recovery environment that is kept in sync rather than promoted to. Every solid arrow is a decision about whether a version belongs on the other end of it.
The environment diagram distinguishes decisions to promote along solid arrows from disaster-recovery environments kept in sync with production. section 2.3
