liveBook · Manning

Artifact promotion

As explained in Kargo in Action

The controlled advancement of an artifact version from one deployment environment to another.

Artifact promotion is the controlled advancement of a specific artifact version between deployment environments. CI builds and publishes an artifact; promotion decides which version belongs in each environment; a GitOps agent deploys the declared state. Keeping these jobs separate makes approval, ordering, artifact identity, and release history explicit rather than leaving them to scripts and convention. section 1.0 section 1.2 section 1.5

In Kargo, a Warehouse discovers versions and records an exact artifact bundle as immutable Freight. Stages form a progression graph: dev can accept Freight directly from a Warehouse, while staging can subscribe to dev so that only Freight verified there becomes eligible. Each advancement creates a persistent Promotion object identifying the Freight, target Stage, and outcome. A Project scopes these resources to a Kubernetes namespace and its RBAC. section 3.2 section 3.2.3 section 3.2.4

Figure 3.1 Kargo’s core resource model. A Project defines the team-or-service scope (a Kubernetes namespace plus its RBAC). Inside that scope, a Warehouse discovers artifacts and produces Freight. A Stage is a node in the promotion graph; it subscribes to Freight, owns a promotion policy, and owns the Promotion objects that record each advancement event. Every Promotion ties a specific Freight to a specific Stage, recording who advanced it and with what outcome.
Kargo core resource model

Use the resource diagram to trace one version from Warehouse to Freight, through Stage subscriptions, and into the Promotion record for each advancement. section 3.2

From image registry to production

Suppose a new application image appears in a registry. Kargo resolves its tag to an exact image and creates Freight. A dev promotion clones the GitOps repository, updates the dev manifest’s image reference, commits and pushes the change, and requests an Argo CD sync. After dev is healthy and any configured tests pass, the same Freight becomes eligible downstream. A production promotion can open a pull request instead of pushing directly, pausing for review before Argo CD syncs production. These are distinct promotions of one recorded artifact version, not a fresh build for each environment. section 1.4 section 3.5

To trigger a manual advancement, create a Promotion in the Project namespace with `spec.stage` set to the destination and `spec.freight` set to an existing Freight name; the Kargo UI and CLI offer other ways to create the same resource. Watch its phase, then check the Git commit, Argo CD Application, and Stage status. A successful Git update alone does not mean the cluster has converged: Argo CD owns reconciliation. The Promotion’s step results and timestamps provide the first audit and diagnostic trail. section 3.2.4 section 3.5.7 section 3.5

If promotion fails at `git-push`, inspect the Promotion’s step status, then check repository write scope, whether the credential Secret is in the Project namespace, and whether its URL format matches the Stage’s repository URL. If staging rejects a version, check whether that Freight was verified in dev: an upstream Stage subscription is an ordering rule, not merely a suggested route. section 3.6.2 section 3.5.7 section 3.2.4

How Kargo in Action covers it

How deep it goes
Walks an end-to-end progression and details resource relationships, triggering, status checks, and a credential failure.
Examples
Follows a container image from registry discovery through dev and staging, with production review and GitOps synchronization.
What it assumes
Assumes a Kubernetes and GitOps delivery context while defining Kargo’s Project, Warehouse, Freight, Stage, and Promotion resources.
What you can do after
Operate/configure it with Kargo resources, verify each advancement, and diagnose failed Promotion steps or rejected downstream Freight.
How it connects
Connects CI, GitOps, immutable artifact identity, Stage subscriptions, verification, RBAC, and pull-request approval.

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.