liveBook · Manning

Promotion record

As explained in Kargo in Action

A promotion record is durable evidence of an artifact's advancement between deployment environments and the decisions associated with that advancement.

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.
Devon’s demo-app pilot with Kargo tracking the environment graph and verification and recording each promotion

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

How Kargo in Action covers it

How deep it goes
Explains record creation, fields, version-bound verification, and configurable retention; defers formal-audit retention requirements.
Examples
Uses an urgent hotfix that carries unintended pre-prod changes and a pilot diagram listing the fields captured for each promotion.
What you can do after
Diagnose/debug with it by tracing a version’s destination, verification, initiator, and outcome, while checking whether retained history reaches far enough.
How it connects
Links artifact revisions, verification, pull requests, environment graphs, and rollback to promotion history.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Kargo in Action. The section links point to the parts of the book it draws on.