Monorepo vs Multirepo for GitOps Manifests: A Practical Guide for Flux and Argo CD

GitOps repository structure is not a style choice anymore. The right answer depends on how you split ownership, reconcile paths, and scale teams, controllers, and environments.

TL;DR

Monorepo versus multirepo is no longer a simple Git preference debate. GitOps tools care about ownership boundaries, reconciliation scope, and how quickly changes should move through the system. Flux can structure monorepos, repo-per-team, and repo-per-app setups, while source decomposition can split a single repository into smaller deployable artifacts with independent lifecycles. Argo CD uses Application paths, automated sync, health assessment, and sync waves to control how Git state becomes cluster state. The best design is the one that keeps ownership explicit, keeps blast radius small, and matches how your platform team actually operates.

The Real Debate Is Not Monorepo Versus Multirepo

GitOps has changed the question. The useful question is not "How many repositories do we want?" It is "Where does ownership live, how does reconciliation happen, and how much blast radius are we willing to accept?"

Under OpenGitOps, the important properties are declarative desired state, versioned and immutable history, automatic pull-based reconciliation, and continuous convergence between Git and the cluster. Those principles do not require a specific repository count. They require a clean contract between the people changing Git and the controller reconciling it.

That is why the old advice around "just put everything in one repo" or "split it all up" breaks down in practice. A monorepo can be clean if you have disciplined boundaries. A multirepo can be a mess if the repo split does not match the actual operating model. The controller matters as much as the repository.

A better framing looks like this:

Monorepo works when the platform team owns most of the surface area and wants a single change stream.
Repo-per-team works when teams need autonomy, permissions, and independent promotion paths.
Repo-per-app works when application release cadence and ownership differ from the platform layers underneath.
Source decomposition matters when one repository should still behave like multiple deployable units.

What GitOps Tools Actually See

Flux and Argo CD do not care about your org chart. They care about sources, paths, artifacts, and reconciliation boundaries.

Flux source-controller acts as a common interface for artifact acquisition. It validates sources, fetches them on demand or on a schedule, packages them into artifacts, and makes those artifacts available to other controllers. That is already a hint that "one repo" is not the only useful unit of deployment.

Flux also goes further with source-watcher and ArtifactGenerator. Those capabilities let you compose multiple sources into a single artifact or decompose a monorepo into multiple independent artifacts. In other words, a single Git repository can still behave like several deployable units if the paths and ownership boundaries make sense.

Argo CD approaches the problem from the Application side. An Application points at a source, a path, and a destination. Automated sync then reconciles desired state in Git against live cluster state. Sync waves and hooks control ordering when one app or one repo contains several resources with real dependencies.

That means the real design variable is often not repository count. It is whether your repo structure matches the reconciliation units your controller understands.

Git repository
  -> source selection / path selection
  -> artifact generation or manifest rendering
  -> application reconciliation
  -> cluster state

Monorepo: Best When One Team Owns the Platform

A monorepo is usually the cleanest starting point when a platform team owns cluster config, app config, and promotion rules.

Flux documents a monorepo pattern with separate directories for apps, infrastructure, and cluster overlays. That is a sane default because it lets you keep the whole platform in one place while still using directory boundaries to prevent chaos.

A practical monorepo layout

gitops-platform/
  apps/
    base/
    staging/
    production/
  infrastructure/
    base/
    staging/
    production/
  clusters/
    staging/
    production/

This layout works because it makes the reconciliation chain explicit:

infrastructure/ contains shared cluster resources.
apps/ contains workload manifests or Helm overlays.
clusters/ defines the exact composition for each environment.

Why monorepo wins

One pull request can update the full platform story.
Cross-cutting changes are easier to review together.
Environment promotion can stay visible in one review flow.
Platform engineers can enforce ordering and dependencies more easily.

Where monorepo hurts

Review noise grows as more teams contribute.
Permissions become harder to partition cleanly.
Large repos can hide ownership mistakes behind directory conventions.
You can accidentally couple app release cadence to platform changes.

Monorepo is not "small team only." It is "one operational model only." If that operational model is real, monorepo is often the simplest and safest choice.

Repo-Per-Team: Best When Ownership Is Distributed

Repo-per-team becomes attractive when the platform team provides the Kubernetes substrate and each product team owns its own deployment intent.

Flux explicitly documents this model: the platform team manages clusters, add-ons, and onboarding, while the dev teams manage their own app definitions and promotion logic. That separation maps well to real orgs because it mirrors who can actually approve changes.

A practical repo-per-team layout

platform-config/
  clusters/
    staging/
    production/
  infrastructure/
    base/
  teams/
    team-a/
    team-b/

team-a-gitops/
  apps/
    base/
    staging/
    production/

team-b-gitops/
  apps/
    base/
    staging/
    production/

Why repo-per-team wins

Teams can move independently without waiting on unrelated changes.
Access control is easier to reason about.
A bad application change does not need to share the same repo as platform bootstrap code.
Platform and product ownership stay visible in code review.

Where repo-per-team hurts

You can duplicate patterns if the platform team does not publish strong templates.
Cross-team changes become multi-PR coordination work.
Drift can increase if each team invents its own conventions.

Repo-per-team is the right answer when autonomy matters more than a single global change stream.

Repo-Per-App: Best When the App Is the Boundary

Repo-per-app is the most natural fit when an application team already owns its source code and deployment manifests together.

In Flux, the config repo can point to app repositories through GitRepository and then reconcile a chosen directory or Helm release into the cluster. The config repo becomes the control plane, while the app repo remains the source of truth for the application itself.

Repo-per-app example

orders-service/
  src/
  deploy/
    manifests/
    helm/

platform-config/
  clusters/
    production/
  apps/
    orders-service.yaml

That split works well when:

application developers own release cadence and config
platform teams want fewer app-specific manifest changes in the central repo
each service has its own lifecycle and rollback story

It works less well when dozens of tiny repos become impossible to govern or when platform changes still need to land in every repo simultaneously.

A Decision Matrix That Actually Helps

Use the following matrix instead of opinion.

Question	Monorepo	Repo-per-team	Repo-per-app
Who owns most changes?	One platform team	Shared platform and product teams	Individual app teams
Need for permissions separation	Low to medium	High	High
Cross-cutting platform changes	Easy	Moderate	Harder
Independent app lifecycles	Medium	High	Highest
Risk of duplicate conventions	Low	Medium	High
Best controller fit	Flux or Argo CD	Flux or Argo CD	Flux or Argo CD

The controller fit row matters. Flux source-controller and source-watcher can reduce the pressure to split repositories too early because path-based decomposition is possible. Argo CD can also narrow the reconciliation boundary with Application paths, automated sync, and sync waves. So the old binary choice is really about how much separation you need, not whether a tool can read another repository.

How Flux Changes the Debate

Flux makes repository shape more flexible because the source system is composable.

The repository-structure guide shows three common layouts: monorepo, repo-per-team, and repo-per-app. That is already a more nuanced view than "one repo or many repos." On top of that, source-controller provides a common interface for fetching and packaging artifacts, and ArtifactGenerator can compose or decompose sources.

The practical effect is important:

A single repo can be split into separate deployable artifacts.
Different paths can have different reconciliation lifecycles.
Multiple sources can be assembled into one deployable unit when needed.

That changes the trade-off. You do not need to split repositories just to create separate operational boundaries. If your team wants one Git repo but multiple deployment lifecycles, Flux can support that.

Flux-style path decomposition example

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: platform-config
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/example/platform-config
  ref:
    branch: main
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: cluster-staging
  namespace: flux-system
spec:
  interval: 10m
  path: ./clusters/staging
  prune: true
  sourceRef:
    kind: GitRepository
    name: platform-config
  wait: true

That pattern keeps a monorepo manageable without pretending the whole repo must reconcile as one blob.

How Argo CD Changes the Debate

Argo CD pushes the same argument from another angle.

An Application specifies a source repository and a path. Automated sync then keeps the cluster aligned with that desired state. If you use separate Applications or ApplicationSets for platform components, add-ons, and workloads, then the repository becomes less important than the Application boundary.

Argo CD also gives you operational control that matters when repositories get larger:

automated sync for pull-based deployment
prune for removing stale resources
self-heal for correcting cluster drift
retry refresh for new revisions during failed retries
sync waves and hooks for ordering dependent resources

Copy-paste Argo CD example

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: orders-service
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/platform-config.git
    targetRevision: main
    path: apps/orders-service/production
  destination:
    server: https://kubernetes.default.svc
    namespace: orders
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
      enabled: true
    syncOptions:
      - CreateNamespace=true

That manifest shows the real unit of control: the Application path, not just the repo.

Ordering example with sync waves

apiVersion: v1
kind: Namespace
metadata:
  name: orders
  annotations:
    argocd.argoproj.io/sync-wave: "-1"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders-api
  namespace: orders
  annotations:
    argocd.argoproj.io/sync-wave: "0"

Use waves when the repo contains dependencies that must land in order, such as namespaces, CRDs, controllers, and then workloads.

Migration Path: Split Only When the Boundary Is Real

Most teams should not jump from monorepo to dozens of repos in one move. That creates governance debt faster than it creates clarity.

Start with the boundary you already have:

Separate platform code from workload code inside the same repo.
Assign clear owners with code review rules and folder conventions.
Split out the highest-churn or highest-isolation workloads first.
Keep cluster bootstrap, add-ons, and app promotion policies under explicit ownership.
Use Flux source decomposition or Argo CD Application boundaries before creating yet another repository.

If the split is still painful after that, then the boundary is probably real and a repo split is justified.

Migration checklist

Move platform bootstrap into its own directory or repo.
Keep shared bases and overlays in one place.
Split application repos only when the teams truly need separate permissions or cadence.
Document who owns CRDs, controllers, namespaces, and namespaces.
Add CI checks that verify repo layout and prevent accidental cross-owner edits.

Common Pitfalls

The worst GitOps architectures usually fail for organizational reasons, not YAML reasons.

Treating repo count as a proxy for ownership clarity.
Letting platform and application teams edit the same manifests without a review boundary.
Mixing bootstrap resources, cluster add-ons, and app workloads in one flat directory.
Splitting repos before you have a promotion strategy.
Using ApplicationSets or repo layouts to hide unclear responsibility.

The fix is not more tooling. The fix is to make boundaries explicit and keep them aligned with how changes are approved.

Why This Is Different Now

The old monorepo-versus-multirepo debate assumed repository boundaries were the primary control surface.

That is no longer true. Flux can decompose sources and reconcile only the paths that changed. Argo CD can reconcile a precise Application path, apply automated sync, and order changes with waves and hooks. OpenGitOps defines the real standard: declarative desired state, immutable history, automatic pull, continuous reconciliation.

Once you accept that, the question becomes much more practical:

Which team owns which boundary?
Which controller owns which lifecycle?
How much coupling is acceptable between platform and product changes?

Answer those questions first. Then choose the repository shape that makes them easy to enforce.

Frequently Asked Questions

Q: Is monorepo or multirepo better for GitOps manifests? A: Monorepo is better when one team owns most changes and wants a single review stream. Multirepo is better when teams need strong isolation, separate permissions, or independent release cadence.

Q: Does Flux favor monorepo or multirepo? A: Flux supports both, and its source tooling makes the choice more flexible. You can keep one repo and still decompose it into smaller artifacts or separate reconciliation paths.

Q: Does Argo CD require a specific repository structure? A: No. Argo CD cares about the Application source path and the desired destination. The important part is how you define the Application boundary and sync policy.

Q: What is the safest way to split a GitOps monorepo? A: Split the most isolated or highest-churn areas first, keep platform bootstrap separate from workloads, and preserve shared conventions before creating more repos.

Q: When should I not split the repo? A: Do not split when the teams, approvals, and release cadence still behave as one system. In that case, a monorepo with strong directory boundaries is usually easier to operate.

Search This Blog

DevOpsDreams