Structuring a Git Repo for Argo CD Multi-Environment Deployments

How would you structure a Git repo for Argo CD when you have dev, staging, and prod environments?

GitOpsbeginner

// interview question

How would you structure a Git repo for Argo CD when you have dev, staging, and prod environments?

Sample answer

Two common patterns exist: environment-per-directory and environment-per-branch. Pick directories. Branches per environment create merge pain, cherry-picking, and drift. Use one branch (usually main) with separate directories for each environment. A layout that works for most teams: apps/ myapp/ base/ # shared manifests (Deployment, Service, ConfigMap) kustomization.yaml overlays/ dev/ # dev patches: replicas, image tag, hostname staging/ prod/ Each environment gets its own Argo CD Application pointing at its overlay path. Base holds what is the same everywhere. Overlays patch only what differs (replicas, resource requests, image tags, ingress hosts, ConfigMap values). If you grow past 20 to 30 environments or clusters, switch from hand-written Application CRs to an ApplicationSet with a Git directory generator so you do not write the same boilerplate over and over.

Why this matters

This is one of the first questions in any Argo CD interview. It separates candidates who have read a tutorial from those who have run this in production. Listen for: a clear preference for directories over branches with a real reason (merge complexity, drift, audit clarity), separation of base from environment-specific patches, and awareness that the layout has to scale past the first three environments. If they immediately reach for branches-per-env, dig in and see if they have actually tried it.

Code examples

Repo layout for a single app across three environments

bash

apps/
  web/
    base/
      deployment.yaml
      service.yaml
      configmap.yaml
      kustomization.yaml
    overlays/
      dev/
        kustomization.yaml
        replicas-patch.yaml
      staging/
        kustomization.yaml
        replicas-patch.yaml
      prod/
        kustomization.yaml
        replicas-patch.yaml
        hpa.yaml
argocd/
  applications/
    web-dev.yaml
    web-staging.yaml
    web-prod.yaml

Argo CD Application pointing at the prod overlay

yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-prod
  namespace: argocd
spec:
  project: production
  source:
    repoURL: https://github.com/org/manifests
    targetRevision: main
    path: apps/web/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: web
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

Common mistakes to avoid

Using a branch per environment and then drowning in cherry-picks and merge conflicts
Putting environment-specific values in a single Helm values file with conditional blocks for prod, then forgetting which branch sets what
Pointing all three environments at the same Argo CD Application path so a dev change ships to prod

Likely follow-ups

Why not use a branch per environment? People still recommend that on blog posts.
How do you handle a config value that has to differ in every single environment?
What changes when dev and prod live in different clusters?
When would you switch from one Application per environment to an ApplicationSet?

Answer out loud first, then check yourself against the model answer.

Practice all Junior questions More GitOps questions

#gitops#argocd#deployments#repository-structure#kubernetes

Also worth your time on this topic

Checklist

Argo CD Multi-Environment Repository Structure Checklist

How to organize your Git repositories when running Argo CD across dev, staging, and production. Covers folder layout, app-of-apps, ApplicationSets, secrets, RBAC, and promotion flow.

60-90 minutes

Article

GitOps with Argo CD: Structuring Your Repository for Multi-Environment Deployments

A practical guide to laying out your Git repository for Argo CD across dev, staging, and production. See real folder structures, Kustomize and Helm patterns, and the pitfalls that bite teams in production.

Interview

Bootstrapping Argo CD and Letting It Manage Itself

Argo CD manages your apps. Who manages Argo CD? Walk me through how you would bootstrap it from a fresh cluster and where its own config lives in your repo.

junior

Structuring a Git Repo for Argo CD Multi-Environment Deployments

More GitOps interview questions

Also worth your time on this topic

Argo CD Multi-Environment Repository Structure Checklist

GitOps with Argo CD: Structuring Your Repository for Multi-Environment Deployments

Bootstrapping Argo CD and Letting It Manage Itself