A promotion record captures an artifact’s advance into an environment as the work happens. A GitOps commit or production pull request shows a repository change, but may not establish what a mutable tag contained or whether pre-prod validated the artifact that shipped. The record makes those questions answerable without reconstructing a release from separate workflows. section 1.1 section 2.5
A useful promotion record identifies:
- The version that advanced and its destination environment. Precise revision identifiers, such as an image digest or Git SHA, keep the artifact unambiguous. section 2.5 section 1.3.2
- Who or what started the advance, how it turned out, and the pull request opened during the transition, where an approval may live. section 2.5
- The associated version state: which environments contain it, which verified it, and which approved it. Verification is recorded against the version tested, not merely against a nearby job run. section 2.5
A Friday hotfix
If a production job simply copies pre-prod, an urgent fix may carry other changes that arrived since the last release. Check the version’s recorded state before advancing it; afterward, use the promotion record to establish what advanced and how the transition ended. A known-good previous state also gives rollback a concrete target instead of relying on where a mutable tag might still point. section 1.1.2 section 2.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 locates the promotion record alongside the environment graph and version-bound verification; its fifth label lists the record’s version, destination, initiator, outcome, and pull request. section 2.5
In Kargo, promotion records are Kubernetes objects. Older records are garbage-collected, with configurable trail depth. Check retention needs before treating the available history as a complete audit trail. section 1.3.2
