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.

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.