Mastering Kargo: Proven GitOps Configuration Practices and YAML Templates

Kargo is a GitOps‑centric delivery platform that automates promotion of workloads across environments. Proper configuration of its custom resources—Warehouse, Stage, and PromotionTemplate—is critical for building scalable, production‑grade pipelines that work with Argo CD and other CI/CD tools.

Why Kargo configuration matters

The robustness and maintainability of a GitOps workflow depend on how you define the Warehouse (artifact source), Stage (environment logic), and PromotionTemplate (promotion steps). Misconfigured resources can lead to silent failures, untracked deployments, and security gaps.

Core Kargo CRDs explained

1. Warehouse

A Warehouse watches image registries or Git repositories and reports new artifact versions. Use semantic version constraints and filters to avoid unstable builds.

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: api-warehouse
  namespace: devops
spec:
  subscriptions:
    images:
    - repoURL: public.ecr.aws/myorg/api
      semverConstraint: ">=1.0.0"

Use semverConstraint instead of the latest tag.

Scope Warehouses per microservice for better isolation.

Monitor logs; misconfigured repositories cause silent failures.

2. Stage

A Stage defines how detected Freight moves to environments such as dev, staging, or prod. It includes promotion rules and approval logic.

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: staging
  namespace: devops
spec:
  requestedFreight:
  - origin:
      kind: Warehouse
      name: api-warehouse
    sources:
      stages:
      - dev
    promotionTemplate:
      spec:
        steps:
        - kustomizeSetImage:
            image: api
            newTag: '{{ .freight.version }}'
        - gitCommit:
            commitMessage: "Promote API to {{ .freight.version }}"
        - gitPush: {}
        - argocdAppUpdate:
            appName: api-staging

Label Argo CD applications with kargo.akuity.io/authorized-stage.

Prefer PR‑based promotion for production environments.

Include rollback strategies where applicable.

3. PromotionTemplate (manual approvals & verification)

Enable manualPromotionApprovals for production stages and add verification steps using Argo Rollouts or custom tests.

apiVersion: kargo.akuity.io/v1alpha1
kind: Stage
metadata:
  name: prod
  namespace: devops
spec:
  manualPromotionApprovals: true
  requestedFreight:
  - origin:
      kind: Warehouse
      name: api-warehouse
    sources:
      stages:
      - staging
    promotionTemplate:
      spec:
        steps:
        - verify:
            analysisTemplate:
              name: rollout-smoke-test
        - kustomizeSetImage:
            image: api
            newTag: '{{ .freight.version }}'
        - gitCommit:
            commitMessage: "Release API {{ .freight.version }} to production"
        - gitPush: {}
        - argocdAppUpdate:
            appName: api-prod

Use the verify step to block bad changes from reaching production.

Notify stakeholders (e.g., Slack, email) while awaiting manual approval.

Track which Freight version is deployed where.

Git repository layout for Kargo

Keep the repository declarative, environment‑segregated, and audit‑friendly. A recommended Kustomize layout:

my-app-gitops/
├── base/
├── overlays/
│   ├── dev/
│   ├── staging/
│   └── prod/

Each overlay is targeted by an Argo CD Application, which Kargo uses for promotion.

Security best practices in GitOps

Lock the prod branch behind PRs.

Store credentials with SealedSecrets.

Rotate Git tokens or deploy keys every 90 days.

Advanced Kargo patterns

Multi‑service promotion

Group related Warehouses or share Stages for tightly coupled applications.

Event‑driven promotion

Trigger external tools (Slack, PagerDuty, etc.) via webhooks after successful promotions.

Failover and canary deployments

Enable automatic rollbacks or combine canary releases with AnalysisTemplates to capture issues early.

Testing strategies

Embed test jobs or hooks inside a Stage:

- verify:
    job:
      name: run-api-tests
      namespace: qa

Conclusion

Correctly configuring Kargo—defining Warehouses, Stages, and PromotionTemplates—creates a secure, scalable, and production‑ready GitOps pipeline. By applying the YAML examples and best‑practice recommendations in this guide, teams can accelerate cross‑environment delivery, reduce promotion errors, maintain a complete Git‑based audit trail, and retain full control over production workflows.