Akuity Guide
/
Kargo
Continuous Promotion
with Kargo
Continuous promotion automatically moves validated software artifacts through successive stages. Kargo, an open-source technology, is gaining traction as one of the tools driving this shift: the 2026 Argo CD User Survey found manual promotions dropping sharply as teams adopt tools like Kargo to automate the process.
This page is a reference for platform teams and DevOps engineers looking to unify multi-environment software delivery rather than relying on manual promotions or CI scripts. It lays out the key concepts and architectural patterns of continuous promotion so platform teams can decide where it replaces hand-rolled promotion scripts and inconsistent rollbacks, instead of adding another layer to maintain.
Key Takeaways
The gap CI and GitOps leave open: CI confirms a build passes tests. GitOps syncs a cluster to Git. Neither decides what moves next, verifies it, or holds a failed stage back.
Meet Kargo: An open-source continuous promotion tool built by the original creators of Argo CD and Akuity. Kargo moves artifacts through stages, enforces verification gates, and maintains an audit trail, replacing shell scripts with policy-driven promotion.
How promotion differs from deployment: Deployment pushes every passing commit to one environment. Promotion governs auditable movement across every stage, with gates at each step.
Completes the GitOps pipeline: Argo CD syncs a cluster to Git. Kargo owns the decision GitOps was never built to make: what moves to production next.
Open source covers the core workflow: Built-in steps for Git, Helm/Kustomize, and Argo CD, no custom scripts required.
Enterprise adds scale and compliance features: promotion beyond Kubernetes, built-in integrations, Custom Steps, and automated rollback.
When to consider Kargo: Most teams get here eventually. Once a team is managing three or more environments, needs a precise rollback, or faces an audit, it's time to evaluate Kargo
What Is Continuous Promotion?
Continuous promotion is the practice of automatically advancing software artifacts (container images, Helm chart versions, configuration packages) through a defined sequence of environments, subject to policy-enforced gates, verification steps, and audit trails at each stage.
Whether or not the final production deploy is automated, this pattern applies the same policies and checks at each step as an artifact moves from one environment to the next.
At scale or in any multi-region rollout, reliable continuous deployment depends on an automated promotion layer. By treating environment hops as a priority, continuous promotion replaces ad-hoc scripts and Slack requests with a clear, automated path that defines how and when artifacts advance.
Continuous Deployment vs. Continuous Promotion
Continuous deployment means automating the push of every passing change into a single target environment. Continuous promotion is the mechanism that governs movement between stages (Dev, Test, or Staging) of a promotion pipeline, regardless of whether the final stage is automated or requires human approval. It continuously syncs individual environments to their desired state.
Deployment is a sync operation: it makes the running state match the desired state. Promotion is a governance operation: it decides whether and when a new desired state should be written for the next environment. GitOps tools like Argo CD handle deployment, but environment promotion requires a separate layer. These are separate concerns and should live in separate tools.
In a GitOps-centric delivery pipeline, deploying a new version to any single environment means editing configuration and letting an agent such as Argo CD sync to that updated source of truth. GitOps alone does not decide that the edit should be made, check that it worked once it landed, or hold the next environment back if it did not. Promotion is that missing layer: the act of making the same change in a controlled, traceable, and reversible way.
The Gap Between CI and GitOps
Why CI and GitOps Can't Own Promotion
CI has a clear job and a clear boundary. It answers one question: does this code build and pass its tests? Its output is an artifact: a container image, a Helm chart, a package. CI tracks build state. It has no concept of "currently running in staging," no model of how environments relate to each other, and no way to enforce environment-level policy across the repositories that define them.
CD has an equally clear job and an equally clear boundary. GitOps tools like Argo CD and Flux take whatever is committed to Git as the desired state and make the running system match it, eliminating drift and providing an audit trail of what was applied. But they take the contents of Git as a given. They do not decide what should be written there next.
That leaves an obvious space between them. Something has to decide that a freshly built artifact is ready for the next stage, verify it once it lands, hold downstream stages when it fails, and record who approved the move. Neither side is equipped to do it, and reaching for the tools on either side of the gap has never worked well. That space is what continuous promotion fills. Read this blog to learn more about why CI/CD pipelines don’t work for Kubernetes.
Challenges Platform Teams Face with Promotion Today
Most teams filled that gap with shell scripts and CI steps. At a small scale, with few environments and infrequent changes, those scripts are good enough.
As environments, regions, and compliance demands grow, and as production incidents require precise rollbacks, the cracks show. Reverting a commit in a deployment repo is rarely the same as reliably restoring a previous running state, especially across multiple files or repos, and after a few forks of the "golden" script, no one is quite sure which version is canonical anymore.
Ad-hoc promotion patterns produce five recurring failures:
Deployment visibility gap: No single source of truth for "what is deployed where." Getting an answer requires cross-referencing CI run logs, Git history, and the live cluster state, and the three sources rarely agree.
Fragile rollback model: Rollback means reverting a commit, which is not atomic, requires understanding the history of multiple files across potentially multiple repositories, and often fails silently if the target state was itself the result of multiple layered changes.
Manual regional rollouts: Promoting to ten regions means ten script invocations with no native coordination, no way to detect partial failures cleanly, and no mechanism to hold downstream regions if an upstream region's verification fails.
Auditing blind spots: Compliance teams cannot get a clean answer to "who approved this release to production and when" without reconstructing the answer from CI logs and Git blame, neither of which was designed for that purpose.
Multi-environment and multicloud sprawl: As services span multiple clusters, regions, and cloud providers, promoting a change consistently across them means juggling different scripts, credentials, and deployment models, with no central control plane to coordinate or pause rollouts when one environment fails verification.
Introducing Kargo: A Continuous Promotion Tool
Kargo is an open-source continuous promotion tool, created to solve environment promotion needs that CI and GitOps tools weren't built to address. Kargo automates the movement of artifacts through stages, enforces verification gates, maintains an audit trail, and supports manual approval workflows. It is built on Kubernetes custom resources and GitOps principles, so it fits naturally into an existing platform engineering stack.
Kargo was created by the team that built Argo CD and was contributed to open source in 2023 to close the promotion gap between CI and GitOps. Kargo is licensed under Apache 2.0 and runs in production at companies globally, including Deutsche Telekom, CiscoThousand Eyes, and, JumpCloud. In addition to open-source Kargo, Akuity also offers Kargo Enterprise, a managed version with additional capabilities covered later in this article.
Kargo Architecture
Where Kargo Fits in a GitOps Stack
In a typical GitOps stack, Kargo sits between "artifact exists" and "desired state is updated in Git." CI builds and publishes images; Kargo watches those sources and decides which versions should move forward based on policy, then writes changes to Git. Argo CD or Flux reconciles from Git into one or more Kubernetes clusters, keeping running state in sync. Kargo does not talk to the clusters directly, and it is not a CI tool: it does not build images, run unit tests, or apply Kubernetes manifests directly.
Kargo’s Core Concepts: Warehouse, Freight, Stage, and Promotion
Here are the key terms used in Kargo, what each means, and the role it plays in the system.
Warehouse: The Kargo component that watches upstream artifact sources, such as image repositories, Helm chart repositories, and Git repositories, and creates Freight when new versions are detected. A Warehouse can subscribe to three categories of artifact sources: container image registries, Helm chart repositories, and Git repositories.
Freight: An immutable reference to one or more artifacts (container image digests, Helm chart versions, Git commits) that moves through Stages as a single unit. A Warehouse creates Freight, which then moves through the promotion pipeline.
Stage: A named promotion target in Kargo representing a specific environment or regional slice of an environment. A Stage maps to a Git path and a deployment target, and it tracks which Freight is currently deployed there.
Promotion: The act of advancing a specific Freight object into a Stage, and the Kubernetes resource that records it. A Promotion writes the artifact references to Git and triggers the downstream sync. Kargo records each Promotion and makes it auditable.
Promotion Pipeline: The directed graph of Stages that defines how Freight flows from early environments to production. Paths can be linear, branching (for multi-region), or convergent (requiring multiple upstream Stages to pass before proceeding).
Project: The team-or-domain scope inside which Warehouses, Stages, Freight, and Promotions live. Each Project gets a corresponding Kubernetes namespace and its own RBAC.
Verification: A check attached to a Stage that must pass before Freight can be promoted downstream. Verifications automate checks such as running an Argo Rollouts analysis, calling an external API, or executing a test job.
Rollback: Re-promoting a Stage's last verified (stable) Freight, using the same Promotion mechanism as a forward move. Because Freight is immutable, this restores an exact prior state rather than reverting a Git commit, avoiding the merge conflicts that can come with reverting across multiple files or repositories.
How Kargo Works
The difference between a dedicated promotion tool and a shell script shows up in what happens at each step between artifact creation and production.
The trigger is the publication of a new artifact version to a source a Warehouse subscribes to: an image pushed to a repositoryregistry, a new chart version, a commit landing on a watched branch. Kargo does not watch the CI system, and no pipeline calls Kargo. CI's job ends when it publishes the artifact.
The Warehouse discovers the new version. A Warehouse subscribes to one or more artifact sources. Its controller polls them on a configured interval, notices the new version, and resolves it to a digest.
The Warehouse produces a Freight object. Kargo identifies Freight by digest, not by tag. On encountering a digest it hasn't seen before, the Warehouse creates a Freight object for it. Because identity is anchored to the digest, the Freight refers to the same bytes even if someone later moves the tag. This is the first durable record in the chain: which artifact, exactly, are we talking about?
A Stage notices the Freight. Each Stage subscribes to a Warehouse or an upstream Stage and carries a policy governing when it accepts new material: automatically, or only after human approval. The Stage controller checks that the Freight is eligible, that policy permits advancement, and that no advancement is already in progress.
The Stage controller creates a Promotion. Before any work begins, it records which Freight is advancing, from where, to which Stage, when, and under what policy. The Promotion records who approved the move and on what evidence.
The Promotion controller runs the promotion steps. Each Stage defines a promotion template: an ordered list of declarative steps. A typical one clones the GitOps repository, updates the artifact reference in that environment's directory, commits, and pushes. The Promotion's status updates as each step runs, and failures land on the object itself rather than in an ephemeral CI log.
Argo CD reconciles the cluster. The push lands a commit, and Argo CD, already watching that repository, reconciles the cluster against the new desired state. Kargo does not replace Argo CD; it produces the commit Argo CD reconciles.
Kargo marks the Freight verified once the environment passes the Stage's health checks, which is what makes it eligible to advance downstream. Had the rollout failed, the next Stage would not see it as a candidate. Eligibility becomes a property of recorded state rather than of human memory.
Kargo Features: From Open Source to Enterprise
Promotion Steps: No Custom Scripts Required (Open Source)
Promotion Steps are modular building blocks that define what happens during a promotion. Kargo ships steps for Git operations (clone, commit, open PRs, tag, push), manifest rendering with Helm and Kustomize, Argo CD operations such as updating Applications or waiting for them to sync, and a generic HTTP step for calling external services. Platform teams get a declarative promotion sequence instead of a pile of shell scripts to maintain.
Read the Promotion Steps reference to learn more.
Hybrid and Multicloud Promotion: One Promotion Layer, Any Target (Enterprise)
Hybrid and multicloud promotion extends the promotion model to any target whose desired state lives in Git, not just Kubernetes. A single promotion sequence can update Terraform-managed infrastructure, restart a VM-based service, and redeploy a serverless function alongside a cluster rollout. Platform teams get one policy-driven promotion layer instead of a separate pipeline per platform.
Read Promotion Support for Kubernetes, Terraform, VMs, and Serverless to learn more.
Built-in Integrations: Approvals and Evidence, Built-In (Enterprise)
Built-in integrations are promotion steps for the systems that already govern your releases: Jira, ServiceNow, JFrog Evidence, GitHub Actions, and Slack or email notifications. A promotion can open a change request, block until it's approved, and record the result without leaving the pipeline. Platform teams get approvals and evidence attached to the same promotion record as the change they authorized.
Read the Promotion Steps reference to learn more.
Custom Steps: Bring Your Own Tooling (Enterprise)
Custom Steps is a container-based extensibility model that lets platform and security teams define their own promotion logic as a native step. An admin registers a step cluster-wide, any team then references it by name in a promotion template, and its inputs, outputs, and results are recorded alongside Kargo's built-in steps. Platform teams get their existing tooling — Terraform, Ansible, OPA policy checks — inside the promotion sequence without waiting for native support.
Read Custom Steps for GitOps Promotion to learn more.
Automated Rollbacks: Recover Without Waking Anyone Up (Enterprise)
Automated rollbacks return a Stage to its last stable Freight when verification fails. Kargo Enterprise detects the failed verification and promotes the previous Freight without anyone needing to notice, decide, and trigger it. Platform teams achieve lower mean time to recovery for exactly the failures that tend to occur outside working hours.
Read Automated Rollbacks in Kargo Enterprise to learn more.
Kargo vs. Alternatives
This gap tends to show up well before a team puts a name to it. Whether an organization requires a tool like Kargo depends on scale, compliance requirements, and how much platform engineering time goes into maintaining promotion infrastructure. Teams running multiple environments, or carrying an audit obligation, should adopt dedicated promotion tooling; a single-application team with two environments should not
Kargo vs. CI Scripts
Scripts in GitHub Actions, Jenkins, or similar tools that commit to Git on CI success are the default for most teams — not because CI systems are good at promotion, but because until recently they were the only option. They stop scaling when a team needs a reliable answer to what is deployed where, coordinated multi-region promotions, an audit trail, or a clean rollback.
For one application across two environments with no compliance obligation, scripts are still the right call and the migration cost isn't worth paying. Teams usually outgrow them at three or more environments, after an incident that demands a precise rollback, or on the way into an audit.
Kargo replaces these CI scripts.
Kargo vs. Custom Kubernetes Operators
Some platform teams build their own promotion operator, which gives them exact control over promotion semantics. The cost is ongoing: as Kubernetes APIs, registry APIs, and delivery practices change, the operator has to keep pace, and that work never appears on a roadmap.
A custom operator is still the right call when your requirements are genuinely unusual and you have the platform headcount to carry it. Kargo is a community-maintained tool with active development, so the same maintenance is spread across a much broader base.
Kargo replaces most custom Kubernetes operators.
Kargo vs. Argo CD
Argo CD reliably reconciles cluster state with Git, and it's the piece Kargo assumes you already have. It doesn't track promotion state, model artifacts as Freight, or enforce promotion policy — teams running Argo CD alone are still solving promotion somewhere else, usually with the CI scripts above.
If you have a single environment and nothing to promote between them, Argo CD alone is sufficient. Kargo decides what gets written to Git, and Argo CD syncs it. Because Kargo writes to Git rather than driving Argo CD directly, it works with Flux or any other GitOps tool.
Kargo runs alongside Argo CD.
Kargo vs. Argo Rollouts
Argo Rollouts handles progressive delivery inside a single environment: canary, blue/green, and automated analysis. It doesn't move a validated artifact from one environment to the next, or decide whether it's allowed to move.
If your delivery problem is entirely about how a change lands in production, Rollouts alone may cover it. Kargo can trigger an Argo Rollouts analysis as a verification step and promote downstream only when it passes.
Kargo runs alongside Argo Rollouts.
Getting Started with Continuous Promotion Using Kargo
The fastest way to see continuous promotion in action is a single promotion path in a non-prod cluster. Setup requires a Kubernetes cluster already running a GitOps controller (such as Argo CD or Flux) and a CI pipeline publishing images to a repository. From there: one Warehouse watching the image, and a single Stage that updates a Git path when a new image appears. Additional stages, verification, and approvals layer in incrementally, without touching existing CI or deployment tools.
The “Kargo Quickstart” walks through building this Warehouse and Stage end‑to‑end and promoting a first change.
Kargo Enterprise: Managed Continuous Promotion
Kargo Enterprise is Akuity's managed platform, providing the governance, integrations, and multi-environment support enterprises need to run continuous promotion at scale, without operating the control plane themselves. Cisco ThousandEyes uses it to automate promotions for 2,500+ applications across 25 environments while continuing to run its own self-hosted Argo CD.
See continuous promotion in action: book a demo, or spin up the Kargo Quickstart on a local cluster and try it for free.
Further Reading and Resources
Kargo Quickstart: build a Warehouse and Stage on a local cluster and promote a first change
Kargo on GitHub: source, issues, and release history (Apache 2.0)
Kargo Discord: Community support channel
Kargo Enterprise: The managed platform and its enterprise capabilities
The Promotion Layer GitOps Was Missing: The Rise of Kargo: origin story and adoption examples
Enterprise GitOps: Multi-Environment Delivery & Promotion: On-demand webinar and demo.
