GitOps Release Management: Building Enterprise Promotion Pipelines with Kargo and Argo CD

How platform teams automate safe Dev → Stage → Production promotions in Kubernetes

Introduction

GitOps has transformed Kubernetes delivery by making Git the single source of truth for infrastructure and application configuration. Tools like Argo CD enable continuous reconciliation between Git repositories and cluster state, allowing platform teams to operate Kubernetes environments declaratively.

However, while GitOps simplifies deployment automation, it does not fully solve one critical challenge: release promotion across environments.

Enterprise software delivery requires structured workflows that safely move artifacts from development to staging and production while maintaining traceability, governance, and approval gates.

This is where Kargo introduces a powerful missing layer in GitOps platforms — release promotion orchestration.

In this article, we explore how platform teams can build enterprise-grade GitOps promotion pipelines using Kargo and Argo CD, enabling safe, automated software delivery across Kubernetes environments.

The Problem with Traditional GitOps Promotion

In a basic GitOps setup using Argo CD, the workflow typically looks like this:

Developer → Git commit → Argo CD detects change → Cluster updated

Argo CD continuously monitors a Git repository and ensures that the Kubernetes cluster state matches the declared configuration.

While elegant, this model introduces challenges when organizations need to:

• Promote artifacts across environments
• Enforce approval gates before production
• Maintain a clear audit trail of releases
• Prevent drift between environments
• Ensure the same artifact is promoted across all environments

Many teams attempt to solve this using:

• Manual pull requests between environment folders
• CI pipelines that modify Git
• Custom scripts managing image tags

These solutions often become complex, fragile, and difficult to audit.

Kargo was designed specifically to solve this problem by adding a promotion orchestration layer on top of GitOps.

Introducing Kargo: A GitOps Promotion Controller

Kargo is a Kubernetes-native promotion controller built to work alongside Argo CD.

While Argo CD handles continuous deployment, Kargo manages promotion workflows between environments.

In simple terms:

ToolResponsibilityArgo CDDeploy Git changes to KubernetesKargoPromote releases between environments

Kargo introduces a structured model for managing promotions using Kubernetes custom resources.

Key capabilities include:

• Tracking application artifacts
• Defining promotion pipelines
• Automating Git updates
• Creating promotion pull requests
• Enforcing approval gates
• Maintaining release traceability

Instead of writing custom scripts, platform teams define promotion workflows declaratively.

High-Level Architecture

A typical enterprise GitOps platform using Kargo and Argo CD contains several layers.

Developer
   │
   ▼
CI Pipeline
(Build + Scan Container)
   │
   ▼
Container Registry + Helm Registry
   │
   ▼
Kargo Warehouse
(Detect new artifacts)
   │
   ▼
Promotion Stages
Dev → Stage → Prod
   │
   ▼
GitOps Repository Updates
   │
   ▼
Argo CD
(Syncs cluster state)
   │
   ▼
Kubernetes Cluster

In this architecture:

1. CI builds container images and helm chart.
2. Kargo detects new artifacts.
3. Kargo promotes artifacts across environments.
4. Git manifests are updated automatically.
5. Argo CD deploys those changes into Kubernetes.

This preserves the GitOps contract: only Git changes trigger deployments.

Repository Structure for GitOps Promotion

A well-organized Git repository is essential.

A common structure looks like this:

gitops-repo/
│
├── applications/
│   └── payment-service
│       ├── base
│       │   └── deployment.yaml
│       │
│       └── overlays
│           ├── dev
│           │   └── values.yaml
│           ├── stage
│           │   └── values.yaml
│           └── prod
│               └── values.yaml
│
└── environments
    ├── dev
    │   └── payment-service.yaml
    ├── stage
    │   └── payment-service.yaml
    └── prod
        └── payment-service.yaml

Each environment references a specific container image version.

Example:

image:
  repository: myrepo/payment-service
  tag: 2026.03.04.1

Kargo updates these tags during promotion.

Core Concepts in Kargo

Kargo introduces several important concepts that form the backbone of promotion workflows.

Warehouse

A Warehouse tracks artifacts such as container images.

Example:

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: payment-service
spec:
  subscriptions:
  - image:
      repoURL: myrepo/payment-service

This instructs Kargo to monitor a container registry for new images.

When a new image appears, Kargo registers it as Freight.

Freight

Freight represents the artifact being promoted.

It includes metadata such as:

• Image tag
• Image digest
• Build metadata
• Commit SHA

Freight ensures artifact immutability across environments.

Stage

A Stage represents an environment.

Typical stages include:

dev
stage
prod

Example Stage definition:

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: dev
spec:
  requestedFreight:
  - origin:
      kind: Warehouse
      name: payment-service

Each stage receives Freight and promotes it forward.

Promotion Templates

Promotion templates define how promotion updates Git.

Example:

apiVersion: kargo.akuity.io/v1alpha1
kind: PromotionTemplate
metadata:
  name: promote-to-stage
spec:
  steps:
  - uses: git-clone
  - uses: update-image
    config:
      path: environments/stage/payment-service.yaml
  - uses: git-commit
  - uses: git-push

This template:

1. Clones the GitOps repository
2. Updates the image tag
3. Commits the change
4. Pushes to Git

Argo CD then deploys the change automatically.

End-to-End Promotion Workflow

Let’s walk through a complete lifecycle.

Step 1 — Developer Commits Code

A developer commits code to the application repository.

git commit -m "feature: add retry logic"

Step 2 — CI Pipeline Builds Image

The CI system builds the container image.

Example tag:

payment-service:2026.03.04.1

The image is pushed to a container registry.

Step 3 — Kargo Detects the Artifact

Kargo Warehouse detects the new image and creates a Freight record.

This artifact becomes eligible for promotion.

Step 4 — Promotion to Development

Kargo promotes the Freight to the dev stage.

It updates the GitOps repository:

image:
  tag: 2026.03.04.1

A commit is created:

promote payment-service 2026.03.04.1 to dev

Step 5 — Argo CD Deploys the Change

Argo CD detects the Git change.

Git change → Argo CD sync → Kubernetes deployment

The dev cluster receives the new version.

Step 6 — Promotion to Staging

After validation or automated tests, Kargo promotes the same Freight to staging.

Promotion may trigger:

• Direct Git commits
• Pull requests requiring approval

Example command:

kargo promote stage

Step 7 — Promotion to Production

Production promotions typically include governance.

Common controls include:

• Pull request approvals
• Security checks
• Canary deployment
• Observability checks

Once approved, Kargo updates production manifests.

Argo CD then deploys the production release.

Promotion Flow Diagram

This ensures the same artifact moves through every environment, eliminating inconsistencies.

Release Promotion Sequence Diagram

Advanced Enterprise Patterns

Large organizations often extend the basic workflow.

Pull Request-Based Promotion

Instead of committing directly to Git, Kargo can create pull requests.

Promotion → Pull Request → Review → Merge → Argo CD Deploy

Benefits include:

• Compliance approvals
• Change tracking
• Security verification

Progressive Delivery

Promotion workflows can integrate with:

• Argo Rollouts
• Service meshes
• Traffic shifting

Example rollout:

10% traffic
30% traffic
60% traffic
100% traffic

This enables safe production deployments.

Multi-Cluster Promotion

Enterprises often run multiple production clusters.

Example:

prod-us
prod-eu
prod-apac

Kargo can promote sequentially across regions.

If you are looking at the Azure Kubernetes as an example, refer to the diagram below.

Benefits of Using Kargo with Argo CD

Best Practices for Production Deployments

Use immutable image tags

Avoid mutable tags such as latest.

Example:

2026.03.04.2

Separate application and GitOps repositories

Recommended model:

app-repo → source code
gitops-repo → deployment manifests

Track promotion metadata

Include metadata such as:

• build ID
• commit SHA
• artifact digest

Implement policy checks

Use admission controllers like:

• OPA
• Kyverno

to enforce deployment policies.

Monitor the promotion pipeline

Integrate observability tools such as:

• Prometheus
• Grafana
• Argo CD metrics

Final Thoughts

GitOps has transformed Kubernetes operations by making Git the control plane for infrastructure and application delivery. However, enterprise platforms require structured promotion workflows to safely move releases across environments.

By combining Argo CD with Kargo, platform engineering teams gain a powerful release orchestration system that maintains GitOps principles while enabling controlled promotion pipelines.

The result is a delivery platform that is:

• Automated
• Auditable
• Secure
• Scalable

For organizations running large Kubernetes platforms, Kargo effectively becomes the release management layer for GitOps.