GitOps Promotion: How Kargo Moves Artifacts from Dev to Production
Carolyn King
Published April 29, 2026 · Updated October 2026 by Carolyn King
Updated October 2026 to cover Kargo v1.10 through v1.12 and Kargo Enterprise 1.11 and 1.12.
TL;DR
Continuous promotion moves a verified, versioned artifact from one environment to the next. Deployment syncs a single environment to its desired state. A healthy GitOps setup keeps the two layers separate.
CI pipelines make poor promotion engines. Custom scripts break when conditions change, rollbacks lack a clean path, and the audit trail lives in build logs.
Kargo, an open source project from the creators of Argo CD, handles promotion while Argo CD handles deployment.
Teams assign each stage one of four promotion modes, from fully automated to emergency bypass. Kargo records who promoted what and when, and since v1.11 a manual rollback holds instead of being overridden by auto-promotion.
Kargo Enterprise adds automated rollback, promotion windows and approvals, Terraform and OpenTofu promotion, change management, and Fleet Management, now in closed beta.
Argo CD solved the first mile of GitOps: it watches a Git repository and continuously reconciles Kubernetes clusters to match the declared state. Teams that reach production scale hit a second problem. Moving a verified artifact from dev to staging to production needs to be controlled, auditable, and repeatable, and most pipelines still handle it with CI scripts and manual steps.
That second mile is continuous promotion, and Kargo exists to solve it. This post covers what continuous promotion is, why it belongs outside CI, how to structure environments for it, and how Kargo and Kargo Enterprise bring the same repeatability and control to promotion that Argo CD brought to deployment.
What is GitOps continuous promotion?
GitOps continuous promotion is the process of moving a verified, versioned artifact from one environment to the next, such as dev to staging or staging to production. A promotion layer decides which artifact moves forward, under what conditions, and with how much human oversight. Deployment then applies that artifact to the target environment.
GitOps uses Git as the source of truth for infrastructure and application state. Teams declare the desired state in a repository, and automated tooling reconciles live workloads to match it. Changes happen by updating Git, not by running imperative commands against a cluster. Promotion extends that model across environments.
For a deeper walkthrough, see Continuous Promotion with Kargo: A Guide for Platform Teams.
Figure: GitOps Environment Promotion
What's the difference between promotion and deployment?
Deployment keeps one environment in sync with its desired state. Promotion governs which artifact moves between environments and what must happen before it does.
Deployment | Promotion | |
Scope | One environment or cluster | The whole pipeline, across environments |
Question it answers | Does this cluster match Git? | Is this artifact ready for the next stage? |
Typical gates | Sync status, health checks | Tests, metrics checks, approvals, change tickets |
Tool | Argo CD, Flux, or another GitOps agent | Kargo |
The two layers work together. The promotion layer feeds the right artifact to the deployment tool at the right time, and the deployment tool reconciles it within each environment. Keeping them separate makes each part of the pipeline easier to reason about, change, and audit on its own.
Figure: Kargo + Argo CD: Promotion & Deployment Layers
Should CI pipelines handle environment promotion?
No. CI systems exist to build and test code, not to govern state across environments. In a typical setup, CI builds an image, runs tests, and on success updates a manifest, opens a pull request, or pushes a tag to trigger a downstream pipeline. That works for one environment. Across many environments and teams, it becomes a hard-to-maintain web of jobs and scripts. Promotion becomes a side effect of the build and four problems follow.
#1: Promotion scripts break when conditions change
Each promotion script reflects the assumptions of its author and the state of the repository when it was written. When those conditions change, the script breaks. New team members inherit logic they can't easily read or safely modify.
#2:Manual promotion introduces human error at the worst moment
Under pressure, during a late-night incident, a hotfix window, or a release crunch, the engineer running the promotion becomes the control plane. That makes manual promotion a correctness problem, not only a process problem.
#3: CI logs make a poor audit trail
When CI artifacts serve as the record of what runs where, basic questions get hard to answer. Which version is in staging right now? Was it promoted automatically or by hand? Did it meet its conditions first? Without a promotion layer, teams reconstruct these answers from build logs.
#4: Rollbacks lack a clean path
Because the promotion happened inside a build, no first-class operation exists to reverse it. Rolling back means rerunning or hand-editing pipeline steps under the same pressure that caused the problem.
How should GitOps environments be structured for promotion?
Most teams organize environments in Git one of three ways, and each trades off audit trail, drift risk, and rollback cost. None of the three solves promotion on its own.
Structure | How it works | Strength | Main risk | Rollback |
Branch per environment | A Git branch per stage; PRs move changes between them | PRs provide an audit trail | Gets unwieldy as stages multiply | Revert a merge |
Folder per environment | One branch, a directory per environment | Simple to manage | Config drift between folders | Revert the folder change |
Repository per environment | A separate repo per environment | Strongest access control boundaries | Coordination overhead across repos | Coordinate reverts across repos |
A fourth pattern, preview environments, provisions a temporary environment for a specific pull request and tears it down when the PR closes.
Whichever structure a team picks, it still needs a layer that governs how artifacts move between environments. The goal is promotions-as-code: promotion logic that is version-controlled, reviewable, and enforced the same way every time, the properties GitOps already brought to deployment. Kargo adapts to the existing structure rather than requiring a reorganization around it.
Figure: Three Structures for GitOps Promotion Environments
What is Kargo and how does it work?
Kargo is an open source continuous promotion tool for GitOps, created and maintained by Akuity, whose founders created Argo CD. Kargo watches registries and repositories for new artifacts, bundles them into versioned units, and moves those units through environments according to rules each team defines. It complements GitOps deployment tools rather than replacing them.
Kargo is an Apache 2.0 project that Akuity co-founders and the co-creators of Argo CD launched in September 2023. It reached v1.0 in 2024, has 3,700+ GitHub stars and 200+ contributors, and runs in production at Deutsche Telekom, Cisco ThousandEyes, and JumpCloud.
Kargo models promotion around three core concepts:
Warehouses subscribe to artifact sources, including Git repositories, container registries, and Helm charts, and detect new versions.
Stages represent environments such as dev, staging, or production. Each Stage defines the conditions an artifact must meet before Kargo promotes it there.
Freight is the unit of promotion: a specific, versioned set of artifacts that moves through the pipeline as one bundle.
Figure: Kargo Core Concepts
This model maps onto each environment structure above. A folder-per-environment setup gets a Stage per folder, and a multi-cluster setup gets Stages that target specific clusters. Because the Git structure and the promotion pipeline stay separate, either can change without breaking the other.
How do teams run promotions with Kargo?
Teams assign each stage a promotion mode, and Kargo handles rollbacks and records each promotion along the way. Match the promotion mode to each stage's risk, the team's tolerance for manual steps, and any compliance requirements. A dev environment that receives dozens of commits a day needs different rules than production. Kargo supports four modes natively, and teams can set a different mode for each stage in the same pipeline.
Mode | How it works | Typical stage | Example |
Fully automated | Kargo promotes Freight to the next stage as soon as it passes defined conditions, with no human step | Dev | A new backend image reaches the shared dev cluster after end-to-end tests, integration tests, and health checks pass |
Policy-gated automated | Promotion runs automatically once verification gates pass: tests, security scans, or metrics thresholds | Staging, canary | A canary version advances only after a low-traffic rollout shows acceptable error rates and stable business metrics |
Manual self-service | An engineer triggers the promotion, and Kargo enforces the required conditions before it proceeds | UAT, production | An engineer promotes a build to UAT once the change ticket is approved and test sign-offs are in place |
Emergency bypass | A team approves Freight directly for a stage, skipping the standard chain while Kargo records who did what | Production hotfix | An on-call engineer approves a hotfix for production without waiting on staging |
Kargo Enterprise 1.12 adds two production controls on top of these modes: promotion windows, which limit promotions to set release hours or block them during a freeze, and approval steps, which pause a promotion until designated reviewers approve it.
How does Kargo handle rollbacks?
In open source Kargo, a rollback is a manual promotion of older Freight to the affected stage. Before v1.11, auto-promotion on that stage would immediately promote the newest Freight again and undo the rollback.
Kargo v1.11 introduced auto-promotion holds. When an engineer manually promotes Freight other than the current auto-promotion candidate, Kargo records a hold that pauses auto-promotion from that Freight's origin. The stage stays where the engineer put it. To resume, the team promotes the current candidate again, and the UI shows a Resume button on held stages.
Kargo Enterprise 1.11 adds automated rollback: when a stage fails verification, Kargo restores the last verified Freight through the same promotion path, with no manual step.
How does Kargo make promotions auditable?
Kargo records each promotion as a Kubernetes resource that captures the Freight, the stage, the steps that ran, the outcome, and the actor who triggered it. That record answers the questions CI logs leave open: what version runs where, how it got there, and who moved it. Releases v1.11 and v1.12 extend the record:
Queryable by stage (v1.11): Kargo labels every promotion with its stage, so kubectl get promotions -l kargo.akuity.io/stage=prod returns a stage's full history.
Kargo metrics in Prometheus (v1.12): Kargo exports metrics for completed promotions, promotion duration, step duration, and stage readiness.
Actor on every API request (v1.12): API server logs name the user or service account behind each request, and Kargo records an event when someone creates or deletes an API token.
Lifecycle events (v1.11 and v1.12): Kargo emits an event when a Warehouse creates Freight and when a pending promotion gets discarded before it runs.
Deep links from promotion steps (v1.11): Steps can output links to the PRs, Jira tickets, or dashboards a promotion touched, and the UI shows them inline.
Kargo Enterprise 1.12 adds custom audit events, which write release details and decisions, such as change-request numbers, to Akuity's central audit log.
The result: promotion history lives in the cluster and in standard observability tools, not in build logs.
What does Kargo Enterprise add?
Kargo Enterprise, part of the Akuity Platform, adds governance, automation, and operational controls on top of open source Kargo.
Capability | What it does |
Automated rollback (1.11) | Restores the last verified Freight when a stage fails verification |
Limits promotions to set release hours, blocks them during freezes, and pauses a promotion until designated reviewers approve it | |
Custom audit events (1.12) | Writes release details and decisions to Akuity's central audit log |
Terraform and OpenTofu promotion | Promotes infrastructure and application changes together, under the same promotion policies |
Jira and ServiceNow change management | Builds formal change requirements into promotion pipelines without custom scripts |
Embedded Argo CD visibility | Shows application state, diffs, and logs in the Kargo UI during a promotion |
Promotion Advisor | Summarizes the commits in a release and assigns an inferred risk score before promotion |
Runs team-defined promotion logic, packaged as containers, next to built-in steps | |
Fleet Management (closed beta) | Coordinates one release across hundreds or thousands of targets with ordered waves, per-target verification, and failure thresholds |
Get started with GitOps continuous promotion
CI scripts produce promotion pipelines that are fragile, opaque, and hard to audit. Treating promotion as a first-class concern, version-controlled, policy-driven, and separate from the build, brings the practices GitOps established for deployment to the second mile. Kargo makes that the default.
Get hands-on: Read the Kargo documentation or start a free trial.
See it in action: Watch How to Simplify & Automate Promotions at Scale or book a demo.
Join the community: Share feedback with the Kargo team on Discord or GitHub.
Frequently asked questions
What is the difference between Kargo and Argo CD?
Argo CD handles deployment: it keeps each Kubernetes cluster in sync with the state declared in Git. Kargo handles promotion: it decides which verified artifact moves to which environment, and when. Most teams run them together, with Kargo feeding Argo CD the right artifact for each stage.
Does Kargo require Argo CD?
No, though most teams run Kargo with Argo CD, and the two integrate most closely. Kargo can also hand off to Flux, a homegrown GitOps controller, or legacy deployment tooling, so teams can adopt its promotion model without changing how they deploy.
Which promotion mode should a production stage use?
It depends on the stage’s risk and any compliance requirements. Manual self-service fits production stages where a person should decide when a release goes out, with Kargo enforcing conditions such as an approved change ticket before the promotion runs. Policy-gated automation fits teams whose tests, security scans, and metrics checks are strong enough to gate production on their own. Emergency bypass is for hotfixes, and Kargo records who approved the Freight. In Kargo Enterprise 1.12, promotion windows and approval steps can sit on top of either mode.
Does Kargo work with a branch-per-environment Git setup?
Yes. Kargo doesn’t require a particular repository layout. Each Stage defines the promotion steps that write to its environment, so a Stage can commit to an environment branch, a folder in a shared branch, or a separate repository. Teams can keep their existing structure and add Kargo on top of it.
How can I see every promotion to a specific stage?
Since v1.11, Kargo labels each promotion with its stage, so kubectl get promotions -l kargo.akuity.io/stage=<stage> lists that stage’s full history, including the Freight, the steps that ran, the outcome, and who triggered it. From v1.12, Kargo also exports promotion metrics to Prometheus.
Can Kargo enforce release freezes and approvals?
Yes, in Kargo Enterprise 1.12 and later. Promotion windows block promotions outside set release hours or during a freeze, and the wait-for-approval step pauses a promotion until designated reviewers approve it. Kargo records each approval with the reviewer, timestamp, and reason.
How does Kargo handle rollbacks?
In open source Kargo, a team rolls back by manually promoting older Freight. Since v1.11, that manual promotion places a hold so auto-promotion doesn't override it. Kargo Enterprise 1.11 adds automated rollback, which restores the last verified Freight when a stage fails verification.
