In the world of modern DevOps, GitOps has quickly become the go-to operating model for managing Kubernetes clusters and applications. But as your workloads grow — and your environments diversify — your GitOps repo structure can either scale with you or become a bottleneck.

Inspired by Stakater’s excellent post, I’ve taken the core concepts and combined them with real-world experience from my multi-tenant GitOps platform using ArgoCD, Helm, and ApplicationSet.

🧠 Why GitOps Repo Structure Matters

A well-structured GitOps repo helps you:

Separate responsibilities across teams
Manage multiple environments (dev, stage, prod)
Onboard new services quickly
Prevent config drift and simplify automation

Bad repo structure? You’ll find yourself debugging tangled YAMLs and trying to reverse-engineer deployment flows.

🏗️ GitOps Repo Structure – Two Key Layers

1. Infrastructure Layer (Platform Components)

This layer includes common configurations that span environments:

common/
├── overlays/
│   ├── dev/
│   ├── stage/
│   └── prod/
└── templates/
    ├── namespace.yaml
    ├── rbac.yaml
    ├── resourcequotas.yaml
    ├── networkpolicy.yaml

🔧 Managed using Kustomize, applied via ArgoCD apps like:

spec:
  source:
    path: common/overlays/dev

2. Application Layer (Per Microservice / Per Team)

This layer includes applications and tenant-specific overrides:

tenants/
└── microservices-team/
    ├── overlays/
    │   └── dev/
    │       ├── values-frontend.yaml
    │       ├── values-cartservice.yaml
    │       └── ...
    └── applicationset.yaml   # ArgoCD dynamically generates apps from the above

📦 All apps use a shared chart:

apps/microservices-demo/charts/
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    └── values.yaml

📌 Environment Segregation Example

Instead of keeping everything under a single dev/ or prod/ folder, each layer handles environment overlays independently:

common/overlays/dev → Namespace, network policies
tenants/microservices-team/overlays/dev → Service configs
clusters/dev/applicationset.yaml → Deploys the right services

This keeps concerns modular and composable.

🔁 ApplicationSet: Automate App Creation from File Discovery

Rather than defining an ArgoCD app per service manually:

- name: cartservice-dev
  path: apps/microservices-demo/charts/cartservice

We use:

generators:
  - git:
      repoURL: ...
      files:
        - path: tenants/microservices-team/overlays/dev/values-*.yaml

Every new file like values-shippingservice.yaml = new app auto-created 🔁

🔐 Secrets and Security

Secrets are handled using SealedSecrets and placed in a dedicated path:

secrets/sealed/dev-app-secret.yaml

This prevents accidental exposure of credentials in Git while still making them GitOps-compatible.

✨ Key Takeaways

Use a layered approach: common/, apps/, and tenants/
Keep Helm templates DRY, centralized under apps/
Use overlays to separate environments cleanly
Let ApplicationSet automate app deployment — Git file = deployment
Secure secrets with SealedSecrets

📚 Further Reading & Credit

This article is inspired by: 🔗 Stakater – GitOps Repository Structure

And implemented in: 🔗 My GitOps Demo Repo

Follow me for upcoming blogs on multi-tenant Kubernetes and GitOps pipelines with CI/CD automation!

#GitOps #ArgoCD #Kubernetes #DevOps #Helm #ApplicationSet #Stakater #MultiTenant

GitOps Repository Structure Explained – Scalable Strategies from Enterprise DevOps