GitOps repo layout for environment promotion

WHAT THIS TESTS Whether you can design a repository structure that makes promotion explicit, reviewable, and free of configuration drift across environments.

A GOOD ANSWER COVERS Favor a directory-based layout over branch-per-environment. A common shape is a config repo with a base holding shared manifests and an overlays or environments tree with dev, staging, and prod, each overriding only what differs using Kustomize patches or Helm per-environment value files. Each environment pins an explicit version, for example an image tag or chart version, so what is deployed where is visible in Git. Promotion becomes a pull request that copies the version already validated in dev into staging's overlay, then later into prod's, giving a clear audit trail and easy rollback by revert. Environment-specific config such as replica counts, resource limits, and endpoints lives in the respective overlay. Many teams separate the application source repositories from the deployment config repository so app CI updates the config repo by bumping a version. The GitOps controller targets each environment's path, often with separate Argo CD Applications or Flux Kustomizations.

COMMON WRONG ANSWERS Branch-per-environment, which causes merge conflicts, cherry-pick drift, and unclear promotion; baking environment values into a single shared file; or letting CI push images directly to prod without a reviewed promotion step.

LIKELY FOLLOW-UPS Why avoid branch-per-environment? How do you gate prod promotion? How does Kustomize overlay precedence work? Mono-repo versus multi-repo?

ONE CONCRETE EXAMPLE The config repo has base/, overlays/dev, overlays/staging, overlays/prod. App CI builds image 1.5.0 and opens a PR setting it in overlays/dev. After dev validation, a second PR sets 1.5.0 in overlays/staging, and finally a reviewed PR sets it in overlays/prod. Each merge triggers the controller to reconcile only that environment, and any bad release is reverted with a single commit.