Kargo Bridges CI and ArgoCD with Streamlined GitOps Promotions

GitOps promises seamless infrastructure as code, but the gap between continuous integration and deployment often creates friction. ArgoCD excels at keeping cluster state synchronized with Git repositories, yet it relies on someone or something to update those Git manifests whenever new container images or Helm charts become available. This handoff point—where CI outputs an artifact and GitOps picks it up—has traditionally required brittle, tightly coupled workflows. Enter Kargo, a continuous promotion platform designed to bridge this gap cleanly while preserving the separation of concerns central to modern DevOps.

The Hidden Friction in GitOps Workflows

Most GitOps setups involve at least two repositories: one for application source code and another for Kubernetes manifests. Continuous integration pipelines build container images, push them to registries, and then attempt to update the manifest repository with the new image tag—often by committing directly to Git. While functional, this approach introduces several pain points:

• Tight coupling: CI pipelines must understand the structure of the GitOps repository, including Kustomize overlays and environment paths. A reorganization in the manifest repo requires updates across multiple CI configurations.
• Environment sprawl: Changes to deployment flows—such as altering how code moves from staging to production—often require editing .gitlab-ci.yml or equivalent files in every service repository.
• Risk of drift: Manual or scripted commits can introduce inconsistencies, especially when multiple teams or services share the same GitOps repository.

Kargo addresses these issues by introducing a dedicated layer between CI and ArgoCD, ensuring that artifact promotion remains consistent, auditable, and decoupled from the build process.

How Kargo Reorganizes GitOps Promotions

Developed by Akuity, the team behind ArgoCD, Kargo does not replace existing tools but instead augments them. It introduces a new category of workflow: continuous promotion, which focuses on updating Git manifests based on artifact availability rather than managing cluster state. The platform’s core components work together to streamline promotions across environments.

Key Concepts and Workflow

Kargo’s architecture revolves around four primary abstractions:

• Warehouses: These act as watchtowers for artifact registries, Helm repositories, and even Git commits. When a new version of an image, chart, or manifest appears, the Warehouse collects these references into a Freight object—a self-contained package that tracks specific artifact versions.

• Freight: Think of Freight as a manifest of manifests. It bundles the precise versions of images, charts, and other dependencies required for a promotion. Freight moves through your pipeline as a unit, ensuring consistency across environments.

• Stages: These represent promotion targets, typically aligned with environments like development, staging, and production. Stages form a pipeline: Freight advances from one Stage to the next only after approval or automatic criteria are met.

• PromotionTasks and ClusterPromotionTasks: These define the actual steps required to promote Freight to a Stage. PromotionTasks are namespaced to a project, while ClusterPromotionTasks are cluster-wide, enabling reusable workflows across multiple applications.

A Typical Promotion Flow

The workflow begins with a developer’s commit. GitLab CI (or any CI system) builds the code, runs tests, and pushes the resulting container image to a registry like AWS ECR. Simultaneously, Helm charts may be published to an OCI registry or Helm repository. At this point, the CI pipeline’s job is complete.

Kargo’s Warehouse detects the new artifact and triggers the creation of Freight. This Freight then enters the development Stage, where a ClusterPromotionTask executes a standardized set of actions:

1. Clones the GitOps repository to a temporary workspace.
2. Updates the relevant YAML file (e.g., a Helm values file or Kustomize overlay) with the new image tag or chart version.
3. Commits the change with a descriptive message.
4. Pushes the update back to the GitOps repository.

ArgoCD, which continuously monitors the GitOps repo, detects the change and synchronizes the cluster to match the new state. The process repeats for subsequent Stages, such as staging and production, with promotions triggered either automatically or manually via Kargo’s user interface.

Standardized Promotions with ClusterPromotionTasks

One of Kargo’s standout features is the separation between ClusterPromotionTasks and PromotionTasks. ClusterPromotionTasks are cluster-wide resources that define reusable promotion logic, while PromotionTasks are scoped to individual projects and can include custom steps.

For example, two ClusterPromotionTasks might handle common scenarios:

apiVersion: kargo.akuity.io/v1alpha1
kind: ClusterPromotionTask
metadata:
  name: promote-image-to-git
spec:
  vars:
    - name: branch
      value: main
    - name: repoURL
      value: git@gitlab.com:org/gitops-repo.git
    - name: yamlPath
      value: overlays/dev/image.yaml
    - name: imageField
      value: spec.image.tag

  steps:
    - uses: git-clone
      config:
        repoURL: ${{ vars.repoURL }}
        checkout:
          branch: ${{ vars.branch }}
        create: true
        path: ./workspace

    - uses: yaml-update
      as: update-image
      config:
        path: ./workspace/${{ vars.yamlPath }}
        updates:
          - key: ${{ vars.imageField }}
            value: ${{ quote(imageFrom(vars.image).Tag) }}

    - uses: git-commit
      as: commit
      config:
        path: ./workspace
        message: "Update image tag to ${{ imageFrom(vars.image).Tag }}"

    - uses: git-push
      config:
        path: ./workspace

apiVersion: kargo.akuity.io/v1alpha1
kind: ClusterPromotionTask
metadata:
  name: promote-chart-to-git
spec:
  vars:
    - name: branch
      value: main
    - name: repoURL
      value: git@gitlab.com:org/gitops-repo.git
    - name: chartPath
      value: overlays/prod/chart.yaml
    - name: chartField
      value: spec.source.targetRevision

  steps:
    - uses: git-clone
      config:
        repoURL: ${{ vars.repoURL }}
        checkout:
          branch: ${{ vars.branch }}
        create: true
        path: ./workspace

    - uses: yaml-update
      as: update-chart
      config:
        path: ./workspace/${{ vars.chartPath }}
        updates:
          - key: ${{ vars.chartField }}
            value: ${{ quote(chartFrom(vars.chart).Version) }}

    - uses: git-commit
      as: commit
      config:
        path: ./workspace
        message: "Update Helm chart version to ${{ chartFrom(vars.chart).Version }}"

    - uses: git-push
      config:
        path: ./workspace

These tasks use variables to remain flexible across different applications and environments. For instance, the repoURL and branch can be set once at the cluster level, while individual Stages override paths like yamlPath or chartPath to target specific overlays. This modularity reduces duplication and makes the system easier to maintain.

Why Kargo Matters for Modern GitOps

Kargo’s introduction reflects a growing recognition that GitOps needs more than just deployment automation—it requires a dedicated system to manage the handoff between CI and GitOps repositories. By decoupling the promotion process from CI pipelines, teams can:

• Simplify CI configurations: Build pipelines no longer need to understand GitOps structures or commit directly to manifests.
• Enforce consistency: Freight ensures that promotions use the correct artifact versions across all environments.
• Improve auditability: Every promotion is tracked, making it easier to trace which image or chart version is deployed where.
• Enable self-service: Non-developers can trigger promotions via Kargo’s UI, reducing bottlenecks in the release process.

As organizations scale their GitOps practices, tools like Kargo will likely become essential for maintaining clarity, efficiency, and control. The future of GitOps isn’t just about synchronizing clusters with Git—it’s about orchestrating the entire lifecycle of artifacts, from build to production, with precision and flexibility.

The gap between CI and ArgoCD is no longer a missing piece—it’s a solvable problem, and Kargo provides the bridge.