Kargo Review: The GitOps Promotion Tool That Actually Makes Sense

If you've been using ArgoCD for a while, you've probably felt the pain of multi-environment promotions. The pattern is always the same: update image tag in Git for dev, wait, update for staging, wait, update for prod. You either automate this with brittle scripts or do it manually and accept that "promote to staging" is a task someone has to remember.

Kargo is Akuity's answer to this problem — a GitOps-native promotion tool that sits on top of ArgoCD and handles the promotion workflow declaratively.

I've been running it in a test environment for a few weeks. Here's what I actually found.

What Kargo Is (and What It Isn't)

Kargo is not a replacement for ArgoCD. It's a promotion orchestrator that works with ArgoCD.

The core concept: Stages and Freight.

• Freight is a versioned bundle of artifacts: a container image tag, a Git commit, a Helm chart version. Think of it as "what we want to deploy."
• Stages are your environments: dev, staging, production. Each Stage subscribes to a Freight source.
• Promotions move Freight from one Stage to the next.

So a typical flow looks like:

New image built → Freight created → 
  Auto-promote to dev → 
  Gate: run tests → 
  Manual approval → 
  Promote to staging → 
  Gate: wait 30 minutes → 
  Manual approval → 
  Promote to production

This is declarative, auditable, and visible in a UI — which is exactly what GitOps promotion has been missing.

Installation

Kargo installs as a set of Kubernetes controllers alongside ArgoCD. With Helm:

helm repo add kargo https://charts.kargo.akuity.io
helm repo update
 
helm install kargo kargo/kargo \
  --namespace kargo \
  --create-namespace \
  --set api.adminAccount.passwordHash="$BCRYPT_HASH"

CLI installation:

# Mac
brew install akuity/tap/kargo
 
# Linux
curl -L https://github.com/akuity/kargo/releases/latest/download/kargo-linux-amd64 \
  -o /usr/local/bin/kargo && chmod +x /usr/local/bin/kargo

The installation is clean. No complicated prerequisites beyond a running Kubernetes cluster with ArgoCD.

Setting Up a Project

Everything in Kargo lives in a Project:

apiVersion: kargo.akuity.io/v1alpha1
kind: Project
metadata:
  name: my-app

Then you define a Warehouse (the artifact source) and Stages:

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-app-warehouse
  namespace: my-app
spec:
  subscriptions:
  - image:
      repoURL: ghcr.io/myorg/my-app
      tagSelectionStrategy: SemVer
      semverConstraint: ">=1.0.0"

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: dev
  namespace: my-app
spec:
  subscriptions:
    warehouse: my-app-warehouse  # Dev subscribes directly to the warehouse
  promotionMechanisms:
    gitRepoUpdates:
    - repoURL: https://github.com/myorg/gitops-config
      writeBranch: main
      kustomize:
        images:
        - image: ghcr.io/myorg/my-app
          path: envs/dev
---
apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: staging
  namespace: my-app
spec:
  subscriptions:
    stages:
    - name: dev  # Staging gets what dev has verified
  requestedFreight:
    - origin:
        kind: Warehouse
        name: my-app-warehouse
      sources:
        stages:
        - dev

Once this is in place, every new image that matches the semver constraint creates Freight in the Warehouse. Dev automatically picks it up. Staging waits for dev to succeed, then requires a manual promotion.

What's Genuinely Good

The audit trail is excellent. Every promotion is recorded: who approved it, when, what Freight moved, what Git commit was created. This is something you'd otherwise have to build yourself with Terraform or custom scripts.

Auto-promotion policies are flexible. You can set dev to auto-promote every new Freight, staging to auto-promote after a delay, and production to always require human approval. This is all declarative configuration.

The UI is actually useful. The Kargo dashboard shows you at a glance what Freight is in each Stage, what's waiting, and what's blocked. For teams managing multiple services across multiple environments, this visibility is valuable.

It works with Kustomize and Helm. The promotion mechanisms support both, and the image tag update logic is smart — it knows how to update kustomization.yaml or Helm values files correctly.

Where It Falls Short

Documentation is thin in places. The concepts page is good, but when you get into more advanced scenarios — multi-cluster promotions, custom verification steps, integrating with specific CI systems — you end up reading source code or asking on Discord.

Verification integration is limited. Kargo supports running Argo Rollouts analysis as a gate between stages, which is powerful. But if you want to gate on external test results (a Selenium suite, a performance test, a QA sign-off in Jira), the integration story isn't as smooth. You can use generic webhook verifications, but it requires extra work.

It's still relatively young. Kargo is at v1.x but the API has evolved quickly. If you adopt it today, expect occasional breaking changes in minor versions. The team is responsive on GitHub, but the ecosystem of plugins and integrations isn't as mature as ArgoCD's.

Learning curve for the Freight model. The concepts of Warehouse → Freight → Stage → Promotion are genuinely different from how most teams think about deployments. I've seen engineers take a couple of days to internalize the model before they can configure things correctly without trial and error.

Kargo vs Manual Promotion Scripts

I want to be honest about this comparison. Many teams manage promotions with a combination of GitHub Actions workflows and ArgoCD. It works. The scripts are maintainable. Is Kargo worth replacing that?

The answer depends on your promotion complexity:

Verdict

Kargo solves a real problem and solves it elegantly. The declarative model for promotions is the right approach, and the ArgoCD integration is solid.

The caveats: it adds operational complexity, the documentation has gaps, and the verification integration story needs work. If you have a simple two-environment setup, you probably don't need it.

But if you're managing three or more environments, running multiple services, and finding that your promotion process is either manual and error-prone or automated with fragile scripts — Kargo is worth adopting. The audit trail and declarative promotion model alone justify it for teams with compliance requirements.

Score: 7.5/10 — Solid tool with real production value, held back by documentation gaps and a still-maturing ecosystem.

Using ArgoCD with Kargo? Check out our ArgoCD complete setup guide and GitOps vs ClickOps.