GitOps Patterns & Practices
Tool choice matters less than structure. These patterns help you organize manifests, promote changes across environments, and use Helm without breaking Git as the source of truth—whether you run ArgoCD or Flux.
Why patterns matter
Without shared conventions, GitOps repos become hard to review, promote, and onboard. Good patterns give you:
- Discoverability — engineers find app and env config quickly
- Safe promotion — the same change moves through environments with clear gates
- Reviewable diffs — PRs show intent, not noise from generated or mixed concerns
- Tool portability — layouts that work with either ArgoCD or Flux
If you are new to the model, read GitOps principles first, then return here to structure the repo.
Pattern map
Start with how the repository is laid out. Promotion and Helm sit on top of that layout. The GitOps controller only consumes what you put in Git.
What you’ll learn
| Guide | What it covers |
|---|---|
| Repository Structure | Monorepo vs multi-repo, app-of-apps / root Kustomization, env overlays, and naming |
| Environment Promotion | Branch, folder, and tag-based promotion from dev → staging → production |
| Helm Integration | Charts, values, and releases under GitOps without push-deploy anti-patterns |
Suggested path
- Structure the repo — Pick a layout in Repository Structure that matches team size and release cadence.
- Define promotion — Codify how changes move environments in Environment Promotion.
- Add packaging — If you use charts, apply Helm Integration so values and versions stay in Git.
Related guides
- ArgoCD Applications & Projects — map folder structure to Applications
- Flux GitOps Toolkit — map paths to Kustomizations and HelmReleases
- CI/CD integration — update image tags or values from CI without bypassing GitOps
FAQ
Should app code and cluster config live in one repo?
Both work. Separate repos reduce blast radius and access scope; a monorepo simplifies atomic changes. Choose based on team ownership and review process—then keep the layout consistent.
Is app-of-apps required?
No, but it scales well: a root Application (ArgoCD) or root Kustomization (Flux) manages child apps so you bootstrap once and grow declaratively.
Where should Helm values live?
In Git, next to the app or environment that consumes them. Avoid “helm upgrade” from CI as the primary deploy path if you claim GitOps.