How do you structure a GitOps repository — app-of-apps, environment folders, overlays?

The way you structure a GitOps config repo determines how easily you can promote changes between environments, onboard new applications, and keep per-environment differences small and reviewable. There is no single correct layout, but three patterns dominate.

1. Kustomize base + environment overlays (most common): Each application has a base/ directory with shared manifests and an overlays/ directory with one folder per environment. Each overlay folder contains a kustomization.yaml that references the base and adds environment-specific patches (image tag, replica count, config values).

gitops-config/
├── apps/
│   └── my-app/
│       ├── base/
│       │   ├── deployment.yaml
│       │   ├── service.yaml
│       │   └── kustomization.yaml
│       └── overlays/
│           ├── dev/
│           │   └── kustomization.yaml  # patches: image tag, replicas=1
│           ├── staging/
│           │   └── kustomization.yaml  # patches: image tag, replicas=2
│           └── prod/
│               └── kustomization.yaml  # patches: image tag, replicas=5
└── argocd/
    └── apps/
        ├── my-app-dev.yaml   # Application CR for dev overlay
        ├── my-app-staging.yaml
        └── my-app-prod.yaml

2. App-of-apps: A single root Argo CD Application points to the argocd/apps/ folder above. Argo CD syncs that folder, creating all the child Application CRs. This allows managing all Application registrations via Git without applying them manually.

3. Separate config repo per environment: Stricter separation — production config lives in a separate repo with tighter branch protection and access control. Suitable for regulated environments but adds overhead when updating shared base configs.

The app repo / config repo split (keeping source code and deployment manifests in separate repositories) is an orthogonal best practice that improves the separation of concerns between CI (build) and CD (deploy).