GitOps Is Incomplete Without Promotion — Here's How Kargo Fixes That
Heba Eid
How Kargo and Argo CD work together to give platform teams end-to-end GitOps control
If you've built a GitOps pipeline on Kubernetes, you're likely familiar with Argo CD — the deployment engine that watches a Git repository and continuously reconciles your clusters to match the declared state. Argo CD solved deployment. But most teams hitting production scale quickly discover there's a second problem: how do you move a verified artifact from dev to staging to production in a way that's controlled, auditable, and repeatable? That's environment promotion, and it's where most GitOps pipelines still rely on CI scripts and manual steps. Kargo was built to solve exactly that.
GitOps is an operational model widely adopted in the Kubernetes ecosystem. It uses Git as the source of truth for infrastructure and application state. The desired state of a system is declared in a Git repository, and automated tooling continuously reconciles the live workload to match it. Changes are made by updating Git, not by running imperative commands against a cluster.
Argo CD solved the first mile of GitOps: it watches a Git repository and reconciles clusters to match the declared state, continuously driving the live Kubernetes environment back toward the configuration checked into Git. The second mile — environment promotion — is where Kargo picks up, governing how verified artifacts move between stages in a controlled, auditable way.
Today, most teams still handle this without a dedicated tool, relying on CI jobs and shell scripts stitched together, with minimal ability to enforce security or compliance checks along the way. It doesn't have to work that way.
In this guide we'll show you how to build secure and scalable environment promotion with Kargo, including:
What GitOps environment promotion is
Why separating promotion and deployment is required for scalable software delivery pipelines
How to structure environments for clean promotion workflows
And, finally, how promotion tools like Kargo and Kargo Enterprise give platform teams the same repeatability, auditability, and control in promotion that Argo CD gave them in deployment.
What Is GitOps Environment Promotion?
Environment promotion is the process of moving a verified, versioned artifact from one stage to the next: from dev to staging, from staging to production. It is distinct from deployment. Deployment is the act of syncing a desired state to a specific environment. Environment promotion is the decision layer that sits above deployment, governing which artifact may move forward, under what conditions, and with what level of human oversight.
Figure: GitOps Environment Promotion
Environment Promotion and Deployment: Why You Should Use Them Together
Deployment is concerned with a single environment or cluster: take this desired state, apply it to this cluster, keep it in sync. Argo CD is a widely adopted tool that many organizations globally leverage for deployment. They watch a Git repository and continuously reconcile the live cluster to match the declared state.
Promotion manages the pipeline as a whole: which artifact has been verified to move from one stage to the next, and what needs to happen before it does. Promotion policies define those conditions, whether that is passing a suite of end‑to‑end and integration tests, a manual approval, a metrics check, or a combination of these.
Figure: Kargo + Argo CD: Promotion & Deployment Layers
Deployment and promotion work together, and a healthy GitOps setup keeps them separate. The deployment tool handles reconciliation within an environment. The promotion layer handles movement between environments, feeding the right artifact to the deployment tool at the right time, under the right conditions. When that separation is maintained, each part of the pipeline becomes easier to reason about, modify, and audit independently.
Why CI Pipelines are the Wrong Tool for Environment Promotion
Most teams promote artifacts between environments by pushing the limit of what their CI system can do. A GitHub Actions job tweaks a manifest, a script opens a pull request, another pipeline pushes a tag, and over time, “environment promotion” turns into a web of duct‑taped jobs and scripts that no one fully understands. When something breaks, rollbacks are painful. When someone new joins, the logic is opaque. Instead of being a first-class concern, promotion becomes a side effect of the build pipeline — and that's where things start to break.
The typical setup looks something like this: CI builds an image, runs tests, and on success triggers a promotion step. That step might be a GitHub Actions job that updates a manifest, opens a pull request, or directly pushes a tag to trigger a downstream pipeline. For a single environment, this is manageable. At scale, it becomes a liability.
The issue is that CI scripts used for promotion are highly customized. Each one reflects the assumptions of whoever wrote it, the state of the repository at the time, and the specific conditions that needed to be handled. As a result, when the conditions change, the script breaks. Add to that, when someone new joins the team, the logic is unclear to them. Importantly, there is no clean path for rollbacks because the promotion was a side effect of a build, not a first-class operation.
More importantly, manual promotion introduces human error at exactly the wrong moment. When an engineer promotes an artifact under pressure — a late-night incident, a hotfix window, a release crunch — they become the control plane. That's not just a process problem. It's a correctness problem. Automation isn't just more convenient here; it's more correct.
There is also a traceability problem. When CI artifacts become the source of truth for what is running in each environment, it becomes difficult to answer basic questions about artifacts, such as which version is in staging right now, was it promoted automatically or manually, and did it meet certain conditions before being moved? Without a dedicated promotion layer, this visibility is either absent or reconstructed painstakingly from CI logs.
CI was designed to build and test. Using it to govern a state across environments is asking it to do a job it was never built for. This isn't an edge case for teams that have grown too fast — it's a structural gap in how most GitOps pipelines are built.
How to Structure GitOps Environments for Promotion
Before you can automate promotion, you need to answer a foundational question: how are your environments organized in Git? The answer matters because your Git structure directly impacts how easy it is to move an artifact forward, and how clean a rollback is.
There are three main approaches.
Branch-per-environment uses separate Git branches per stage, with pull requests providing an audit trail. It's intuitive but becomes unwieldy at scale, and rollbacks mean reverting a merge.
Folder-per-environment keeps everything on a single branch with environment configs in separate directories — simpler to manage, but prone to config drift if discipline slips.
Repository-per-environment gives each environment its own repo, offering the strongest access control boundaries, but coordination across repos adds overhead for both promotion and rollback.
Figure: 3: Structures for GitOps Environments
A fourth pattern worth noting is preview environments — temporary, on-demand environments provisioned for a specific pull request and torn down once it closes.
None of these structures solves the promotion problem on its own. Whichever approach you use, you still need a layer that governs how artifacts move between environments in a controlled, auditable way. The goal, regardless of structure, is promotions-as-code: promotion logic that is version-controlled, reviewable, and enforced consistently — the same properties GitOps gave you for deployment.
Even if you’re still working on your structure, Kargo is flexible and adapts rather than requiring you to reorganize around it.
Kargo: Open-Source GitOps-Native Environment Promotion
Kargo is an open-source continuous promotion tool built by the creators of the Argo project. It was designed to solve the promotion problem specifically, without requiring teams to create custom CI scripts or manage promotion logic inside their build pipelines. Kargo complements GitOps tools such as Argo CD rather than replacing them: Argo CD handles deployment, Kargo handles the promotion decisions that feed it.
Kargo models promotion around three core concepts.
Warehouses subscribe to artifact sources, including Git repositories, container registries, and Helm charts, and detect when new versions are available.
Stages represent environments like dev, staging, or production that make up the promotion pipeline. Each stage has defined conditions that must be satisfied before an artifact, called Freight in Kargo's model, can be promoted into it.
Freight is the unit of promotion: a specific, versioned collection of artifacts that moves through the pipeline as a coherent bundle.
Figure: Kargo Principles
This model maps cleanly onto any of the environment structures described above. A folder-per-environment setup can have a corresponding Stage for each folder. A multi-cluster setup can have Stages that target specific clusters. The Git structure and the promotion pipeline are kept separate, which means either can evolve without breaking the other.
Kargo also works with any deployment tool, not just Argo CD. Teams can pair Kargo’s promotion layer with whichever sync mechanism fits their stack, whether that’s Argo CD, Flux, a homegrown GitOps controller, or even legacy deployment tooling like Jenkins or custom shell scripts. That means you can adopt Kargo’s promotion model without having to rewrite your existing deployment strategy.
How to Choose a Promotion Strategy for Each Environment
Different stages call for different promotion approaches. A dev environment that receives dozens of commits per day should not have the same promotion requirements as a production environment serving real users. The right approach depends on the risk level of the stage, the team's tolerance for manual steps, and any compliance requirements that apply.
Four modes cover the range of what teams typically need.
Fully automated promotion requires no human involvement. When an artifact passes defined conditions in one stage, Kargo automatically promotes it to the next. This is appropriate for low-risk stages like dev, where speed matters more than caution. For example, promoting a new backend service image to a shared dev cluster as soon as it passes a suite of end‑to‑end and integration tests, plus basic health checks.
Policy-gated automated promotion runs automatically but requires verification steps to pass first. These might include integration tests, security scans, or metrics thresholds. Promotion proceeds only when all gates are satisfied. For example, a new canary version of a service may be promoted only after a low-traffic rollout shows acceptable error rates and stable business metrics.
Manual self-service promotion puts a human in the loop but provides guardrails. An engineer triggers the promotion, but Kargo enforces the conditions that must be met before it can proceed. For example, an engineer might promote a build into UAT only after a change ticket is approved and required test sign-offs are in place.
Emergency bypass allows a team to skip the normal pipeline and promote directly to a stage when speed is critical, such as deploying a hotfix to production. Kargo supports this via direct stage approval, which bypasses the standard promotion chain while still creating an auditable record of what was done and who did it.
Kargo supports all four modes natively, and teams can configure different modes for different stages within the same pipeline. The right choice for dev is rarely the right choice for production, and a well-configured Kargo pipeline reflects that.
For teams operating at enterprise scale, getting these promotion patterns right isn’t just a matter of convenience—it’s a governance, auditability, and risk management problem. That’s where Akuity’s enterprise offering around Kargo comes in.
Enterprise GitOps Environment Promotion with Akuity & Kargo
Kargo is available as an open source project, and Akuity provides an enterprise-grade offering through the Akuity Platform.
Kargo Enterprise: Governance and Auditability at Scale
Kargo Enterprise adds the governance, auditability, and operational controls that production teams in regulated or complex environments require. Enterprise capabilities include Terraform and OpenTofu support, which brings infrastructure promotions into the same workflow as application promotions. Rather than managing infrastructure changes through separate CI pipelines, teams can promote both application and infrastructure updates together as a single, coordinated operation. Kargo handles the sequencing, and the entire process is governed by the same promotion policies as everything else in the pipeline.
Built-In Change Management and Argo CD Visibility
Kargo Enterprise also integrates with enterprise platforms like Jira and ServiceNow, allowing teams to incorporate formal change management requirements directly into their promotion pipelines without maintaining custom scripts. Embedded Argo CD visibility inside the Kargo UI means engineers can inspect application state, review diffs, and stream logs without switching tools during a promotion.
AI-Assisted Promotion Decisions with Kargo’s Promotion Advisor
Within this enterprise context, Kargo's Promotion Advisor brings AI-augmented intelligence to the release process. Before a promotion occurs, the Advisor enumerates the commits associated with the release, analyzes code diffs and commit messages, and produces a summary along with an inferred risk score drawn from promotion history across stages. Engineers can ask the Advisor why a change might be risky and receive reasoning grounded in the actual code and deployment history. This turns promotions from status-driven actions into context-driven decisions.
Extensible Promotion Logic for the Organization
Kargo Enterprise includes Custom Steps: a container-based extensibility model that lets platform teams define and run any promotion logic their organization requires — security checks, policy validation, vulnerability scanning, or integration with internal tooling — natively inside Kargo alongside built-in steps. Build it once, and every team in the organization can use it, with every step recorded in the Kargo promotion record as part of the promotion contract.
Start Doing GitOps Environment Promotion the Right Way
Most teams reach for CI scripts when they need environment promotion — and end up with a pipeline that's fragile, opaque, and hard to audit. The better path is to treat promotion as a first-class concern: version-controlled, policy-driven, and separate from your build pipeline. That's the best practice GitOps established for deployment, and it applies equally to promotion. Kargo brings it to life.
If you're ready to close the second mile of GitOps, here's where to go next:
Get hands-on: Visit the Kargo documentation or start a free trial today
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
