cloud-native-gitops-workflows

GitOps Workflows and Promotion

Purpose

Make Git the declarative source of truth for cluster state, with a promotion path from dev to production that is reviewable, reversible, and does not put secrets in Git. The design decisions are repo layout, how changes move between environments, and how secrets and rollouts integrate.

Agent Protocol

Trigger

"gitops workflow", "environment promotion", "app of apps", "ApplicationSet", "multi-cluster gitops", "secrets in gitops", "sealed secrets", "external secrets", "gitops repo structure", "flux vs argocd".

Input Context

• GitOps engine (Argo CD or Flux), number of clusters/environments, tenancy.
• Templating (Kustomize, Helm), secret backend (Vault, AWS/GCP/Azure secret managers).
• Release cadence and approval requirements.

Output Artifact

Directory layout, Argo CD/Flux manifests, promotion procedure. No file unless requested.

Response Format

Engine: {argocd|flux}
Repo model: {mono config repo|repo per team} + {folders per env}
Promotion: {PR from env A to env B | image-updater | CI commit}
Secrets: {ESO|Sealed Secrets|SOPS}
Multi-cluster: {ApplicationSet generator|Flux Kustomization per cluster}

Completion Criteria

• No plaintext Secrets in Git.
• Promotion to production requires a reviewed PR (or protected automation).
• Drift is detected and either self-healed or alerted.

Repository Layout (folders per environment)

platform-config/
├── apps/
│   └── checkout/
│       ├── base/                 # Deployment, Service, HPA, kustomization.yaml
│       └── overlays/
│           ├── dev/              # image tag, replicas, config for dev
│           ├── staging/
│           └── prod/
├── clusters/
│   ├── prod-eu-1/               # what runs on this cluster (Applications or Flux Kustomizations)
│   └── prod-us-1/
└── infrastructure/              # ingress controller, cert-manager, ESO, policies

Environment-per-folder beats environment-per-branch: branches drift, merges between long-lived branches pull unrelated changes, and diffs between environments become hard to read. Keep app source code and deployment config in separate repos (or at least separate paths) so CI commits to config do not retrigger app builds.