How do you handle multiple environments (dev/staging/prod) in a GitOps repo?

The most common and maintainable approach is Kustomize base + overlays: shared manifests live in a base/ directory, and each environment has an overlay directory that patches only what differs — typically the container image tag, replica count, resource limits, and environment-specific ConfigMap values.

# apps/my-app/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namePrefix: prod-
commonLabels:
  env: production
images:
  - name: my-app
    newName: registry.example.com/my-app
    newTag: v1.5.2
patches:
  - patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
    target:
      kind: Deployment
      name: my-app

Each environment has its own Argo CD Application or Flux Kustomization CR pointing to its overlay path. Promotion between environments is a PR that updates the image tag in the next environment's kustomization.yaml.

Promotion workflow example:

1. CI builds image, tags it v1.5.2, pushes to registry.
2. CI opens a PR updating overlays/dev/kustomization.yaml with tag v1.5.2.
3. GitOps operator deploys to dev. Team verifies.
4. Engineer opens a PR to update overlays/staging/kustomization.yaml to v1.5.2.
5. After staging validation, a final PR promotes overlays/prod/kustomization.yaml to v1.5.2.

Alternative: Helm with per-environment values-dev.yaml, values-prod.yaml files. Flux HelmRelease CRs reference the appropriate values file per environment. Less DRY for structural differences but cleaner for apps already distributed as Helm charts.