CI can build and test an artifact, and Argo CD can keep a cluster synchronized with Git, while neither decides which tested artifact should advance to production. That decision is promotion. When scripts, scheduled jobs, and pull requests make it implicitly, teams may struggle to prove what shipped, who approved it, or whether the exact artifact passed pre-production checks. section 1.0 section 1.1
A promotion control plane makes advancement between environments an explicit, governed process. It tracks candidate versions, observes when conditions for advancement are met, carries out permitted transitions, and records each event. It does not replace CI’s build or a GitOps agent’s deployment work: it governs what should enter the desired state that the agent reconciles. section 1.1 section 3.1
A useful test is whether you can answer these questions without reconstructing pipeline runs and commits:
- Is production running the exact artifact that passed pre-production validation? section 1.1.1
- Who approved that version, when, and with independent review where required? section 1.1.1
- Can you trace it from commit to image to each environment, and show that pre-production could not be skipped? section 1.1.1
The distinction from a promotion job matters operationally. A job runs and exits; to enforce a two-hour soak, a workflow must schedule checks. A controller runs continuously, observes versions and environments, and notices when a declared condition becomes true. Centralizing that logic also avoids teams maintaining divergent definitions of “ready.” section 2.5 section 2.6
One image through dev, staging, and production
In Kargo, a Warehouse discovers an image version from a registry and Freight identifies an immutable artifact set by digest. Stages represent positions in the environment graph. A Promotion records an advancement: dev can write the selected version to a GitOps repository, which Argo CD then reconciles into the cluster. After verification in dev, the same Freight can advance to staging and onward to production under the applicable conditions. A Project groups resources for a team or domain. The digest, rather than a mutable tag alone, identifies what moves. section 3.0 section 3.7 section 1.5
Figure 2.5 Devon’s demo-app pilot, drawn like figure 2.1 for comparison. Each numbered label matches the same property there: (1) the system runs continuously rather than on a schedule; (2) one installation serves every team; (3) it records where each version is in the environment graph; (4) verification is recorded against the version it tested; (5) every promotion leaves a record naming the version, the environment, who started it, the outcome, and the pull request.
The pilot diagram contrasts recurring jobs with one continuously running system and shows how version position, verification, and promotion records become visible together. section 2.5
When a first promotion stalls, inspect the affected resource with `kubectl describe` and check the responsible controller. Common causes are registry credentials, Git push permissions, Argo CD sync configuration, and stage ordering. For installation, verify that CRDs are present, controllers are healthy, and RBAC bindings exist. This additional layer is most valuable across multiple environments or teams, or where compliance matters; it is not presented as a fit for non-Kubernetes workloads or genuinely simple delivery. section 3.7 section 1.5
