Kargo — GitOps Promotion and Application Lifecycle Orchestration

Introduction

Kargo solves the promotion problem in GitOps: how do you safely move a change from dev to staging to production with verification at each step? Built by the creators of Argo CD, Kargo provides a declarative way to define promotion pipelines that advance artifacts through stages with automated gates and rollback capabilities.

What Kargo Does

• Defines multi-stage promotion pipelines (dev → staging → production) as Kubernetes resources
• Watches for new container images, Helm chart versions, or git commits as promotion triggers
• Runs verification steps (tests, smoke checks, analysis) between promotion stages
• Integrates natively with Argo CD for the underlying GitOps delivery
• Provides a visual UI showing the promotion state of every artifact across all stages

Architecture Overview

Kargo introduces custom resources: Projects, Stages, Warehouses, and Promotions. A Warehouse watches artifact sources (container registries, Helm repos, git branches) for new versions. When a new artifact appears, Kargo creates a Freight object representing that version. Promotions advance Freight through Stages, where each Stage can run verification steps before allowing further promotion. The controller updates git repositories or Argo CD Application specs to trigger the actual deployment.

Self-Hosting & Configuration

• Requires Argo CD already installed on the target cluster
• Deploy via the official Helm chart into a dedicated namespace
• Define Projects that map to your application teams or services
• Configure Warehouses pointing to your container registries or chart repositories
• Set up verification steps using Argo Rollouts AnalysisTemplates or custom jobs

Key Features

• Declarative promotion pipelines replace manual scripts for moving changes between environments
• Freight tracking provides full audit trail of which versions are deployed where
• Verification gates run automated checks before allowing promotion to the next stage
• Native Argo CD integration means no parallel deployment mechanism is needed
• Automatic rollback reverts a promotion if verification fails at any stage

Comparison with Similar Tools

• Argo CD — handles GitOps deployment; Kargo adds the promotion orchestration layer on top
• Argo Rollouts — progressive delivery within one environment; Kargo manages across environments
• Flux — GitOps delivery without built-in promotion pipelines; Kargo fills that gap
• Spinnaker — full CD platform with promotion; Kargo is lightweight and Kubernetes-native
• Harness — enterprise CD with pipelines; Kargo is open-source and GitOps-native

FAQ

Q: Do I need Argo CD to use Kargo? A: Yes. Kargo is designed as a companion to Argo CD, adding promotion orchestration on top of its GitOps delivery capabilities.

Q: How does Kargo differ from just using multiple Argo CD Applications? A: Multiple Applications handle deployment but not promotion logic. Kargo adds versioned Freight tracking, verification gates, and declarative promotion policies that connect stages together.

Q: Can Kargo handle monorepo setups with multiple services? A: Yes. Each service can be a separate Kargo Project with its own Warehouses and Stages. Promotions are independent per project.

Q: What happens if a verification step fails during promotion? A: The promotion is marked as failed and the Freight does not advance to the next stage. Depending on configuration, Kargo can automatically roll back or wait for manual intervention.

Sources

• https://github.com/akuity/kargo
• https://docs.kargo.io