Repository Structure for GitOps
What you'll learn: How to organize your GitOps repositories for clarity, maintainability, and safe multi-environment deployments.
The Core Challenge
When adopting GitOps, one of the first questions is: "Where does everything go?" Poor repository organization leads to tangled configs, risky changes, and confused teammates. Good structure makes reviews easy, rollbacks safe, and environments clear.
Key Organizational Patterns
Separating Config from Code
Keep application source code separate from deployment manifests. Your app repo should contain business logic; your GitOps repo contains Kubernetes YAML, Helm values, or Terraform configs. This separation lets different teams own different concerns and prevents accidental production changes during feature development.
Think of it like separating recipes (code) from kitchen layouts (infrastructure)—they evolve independently.
Environment Branches or Directories
You can organize environments in two ways:
- Branch-per-environment:
mainbranch for production,stagingbranch for staging. Promotions happen via pull requests between branches. - Directory-per-environment: Single branch with
/environments/dev,/environments/staging,/environments/prodfolders.
Directories are simpler and make cross-environment comparisons easier. Branches provide stronger isolation but complicate side-by-side audits.
The App-of-Apps Pattern
Instead of one massive YAML file, create a root application that references child applications. Each microservice or component gets its own folder with manifests. The root app orchestrates everything, making it easy to add/remove services without touching unrelated configs.
This is like a master playlist that references individual songs—you manage the collection without rewriting every track.
Key Takeaway: Structure GitOps repos with clear config/code separation, consistent environment organization (prefer directories), and an app-of-apps pattern for managing multiple services—this keeps your infrastructure code reviewable, testable, and safe.