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).

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.