A cryptographic hash gives an artifact a content-derived identity. In a container registry, that identity appears as an image digest. A tag such as `1.2.0` is useful to read, but it can later be repushed to point at a different image. Resolving the tag to a digest when the artifact is discovered preserves the identity of the build selected for promotion. section 1.3.3 section 3.2.2
A Warehouse discovers an artifact version and creates a Freight object that records both its tag and digest. Freight is not authored by hand. Its content-derived name identifies the bundle, while its `origin` identifies the Warehouse that produced it. A Freight can also bundle image, chart, and Git versions so a Stage advances a coherent set rather than an arbitrary mix. section 3.2.2
Listing 3.2 A Freight object as Kargo creates it (illustrative, not for authoring)
apiVersion: kargo.akuity.io/v1alpha1
kind: Freight
metadata:
name: 7b2f9a8e3c1d5f4a6b8e9c0d2f1a5b7c # #1
namespace: demo
spec:
origin:
kind: Warehouse
name: demo-app # #2
images:
- repoURL: ghcr.io/kargobook/demo-app
tag: 1.2.0 # #3
digest: sha256:a3b9e7f2c1d4f8a2b6c4e1d7 # #4
The illustrative Freight listing shows the readable `tag` beside the identifying `digest`, plus the content-derived name and Warehouse origin. Inspect these fields when tracing which build was promoted; do not apply the listing as a hand-authored resource. section 3.2.2
Follow a promoted image
A new `demo-app:1.1.0` image reaches the registry. The Warehouse discovers it and creates Freight pinned by digest. A Promotion updates the dev GitOps overlay, and Argo CD syncs the resulting commit. To check the result, inspect the Git commit, Argo CD Application, Stage status, and Freight: the overlay change shows the requested tag, while Freight records the stable artifact identity. Do not treat the tag alone as proof of which image was selected. section 3.5 section 3.5.7





