From Commit to Production: GitOps Promotion Workflows with Kargo & Argo CD

Promotion between environments is one of the most challenging aspects of continuous delivery when you're operating under GitOps principles. You've got Argo CD doing an excellent job of reconciling your cluster state with what's declared in Git — but how do you actually move a new version of your application from dev to staging to production in a way that's traceable, safe, and automated?

That's exactly the problem Kargo was built to solve.

In this article, we'll walk through what Kargo is, how it integrates with Argo CD, and how you can design a complete GitOps promotion workflow that takes your application from a freshly pushed container image all the way through to production — with guardrails at every step.

The Promotion Gap in GitOps

If you've worked with GitOps for any length of time, you've likely encountered a frustrating irony: GitOps is wonderful at synchronizing desired state to a cluster, but it offers almost no guidance on how to propagate changes from one environment to the next.

In a typical Argo CD setup, you might have three Application resources — one each for dev, staging, and production — each pointing at different directories or value files in a Git repository. Promoting a new version means manually (or via CI scripts) updating the image tag in the right file, committing it, and waiting for Argo CD to pick up the change. This works, but it introduces several problems.

First, there's no unified view of what version is running where. Second, promotion logic ends up scattered across CI scripts, webhook handlers, and ad-hoc shell commands. Third, there's no built-in concept of verification gates — you can't easily say "only promote to production after staging has been healthy for 24 hours." And finally, rollback becomes a manual Git revert operation rather than a first-class workflow.

Kargo addresses all of these concerns by introducing a promotion-native layer on top of the GitOps ecosystem.

What Is Kargo?

Kargo is an open-source, continuous promotion platform built and maintained by the creators of the Argo project at Akuity. It's designed specifically to orchestrate the movement of application artifacts — container images, Helm charts, Git commits — through the stages of your application's lifecycle using GitOps principles.

Rather than replacing Argo CD, Kargo complements it. Argo CD remains responsible for synchronizing cluster state with Git. Kargo takes over the job of deciding what gets promoted where and when, and then making the corresponding changes in Git so that Argo CD can do what it does best.

A few key design decisions make Kargo stand out. It's entirely declarative — your promotion pipelines are defined as Kubernetes custom resources. It's unopinionated about your deployment tooling — it works with Helm, Kustomize, raw manifests, or any combination. And it treats promotion as a first-class, auditable operation rather than a side effect of a CI pipeline.

Core Concepts

Kargo introduces a small set of new concepts that are worth understanding before diving into configuration. The terminology is deliberately drawn from logistics and shipping — an analogy that makes the mental model surprisingly intuitive.

Projects

A Kargo Project is the top-level unit of organization and tenancy. It maps directly to a Kubernetes namespace and contains all the resources that define one or more promotion pipelines. Projects also serve as the boundary for RBAC rules and policies, such as whether auto-promotion is permitted for certain stages.

Warehouses

A Warehouse is where promotable artifacts originate. It subscribes to one or more artifact sources — container image registries, Git repositories, or Helm chart repositories — and watches for new versions. When a new artifact revision is discovered, the Warehouse packages the latest revisions of all its subscribed artifacts together into a new piece of Freight.

Think of a Warehouse as a loading dock that receives shipments of new software versions and prepares them for distribution through your pipeline.

Freight

Freight is Kargo's most distinctive concept. A single piece of Freight is a "meta-artifact" — a set of references to specific versions of one or more artifacts. For example, a piece of Freight might reference version v1.5.2 of your container image and commit abc123 from your config repository. The key insight is that these artifacts travel together as a unit through the promotion pipeline, ensuring that related changes are always promoted in lockstep.

Every piece of Freight is represented as an immutable Kubernetes resource. It gets a SHA-1-based name for programmatic use and a human-friendly alias (like fruitful-ferret) for easy identification in the UI and CLI.

Stages

Stages are the most important concept in Kargo. A Stage represents a specific instance of your application — typically corresponding to what you'd informally call an "environment" like dev, staging, or production. Kargo deliberately avoids the term "environment" because a stage's name denotes its purpose, not necessarily its physical location.

Stages can be linked together to form a promotion pipeline. Each stage declares what Freight it accepts (either directly from a Warehouse or from upstream stages) and defines a promotion template that describes the steps to execute when Freight arrives. These steps typically involve cloning a Git repo, updating image tags or Helm values, committing the changes, pushing them, and then triggering an Argo CD sync.

Promotions

A Promotion is simply a request to move a specific piece of Freight into a specific Stage. Promotions can be triggered manually through the UI or CLI, or they can happen automatically based on policies you define at the project level.

How Kargo and Argo CD Work Together

The integration between Kargo and Argo CD follows a clean separation of concerns. Here's the typical flow:

1. CI builds and pushes a new container image to a registry.
2. Kargo's Warehouse detects the new image version and creates a new Freight resource.
3. A Stage picks up the Freight (either via auto-promotion or manual trigger) and executes its promotion template.
4. The promotion template clones your GitOps repo, updates the relevant configuration (image tags, Helm values, etc.), commits the change, and pushes it back.
5. Argo CD detects the Git change and synchronizes the cluster to match the new desired state.
6. Optional verification runs (health checks, smoke tests, analysis templates) to confirm the promotion was successful.
7. The Freight is marked as verified in this stage, making it eligible for promotion to the next stage in the pipeline.

This cycle repeats at each stage, with Kargo managing the flow and Argo CD handling the actual deployment. The Argo CD Application resources need a special annotation — kargo.akuity.io/authorized-stage — to ensure that only the designated Kargo stage can trigger updates to that application.

Let's walk through building a three-stage promotion pipeline (dev → staging → prod) for a typical microservice.

Refer to my medium post article for more details.