GitOps patterns for repository and folder/directory structure

My insights on GitOps repo and folder/directory structure patterns after combining my own experience with these awesome resources:

:film_projector: GitOps: Core Concepts & Ways of Structuring Your Repos by Pinky Ravi and Scott Rigby (Weaveworks)

:newspaper: How to set up your GitOps directory structure by Christian Hernandez (Codefresh) and

:newspaper: How to Model Your Gitops Environments and Promote Releases between Them or :film_projector: the talk at ArgoCon 22 by Kostis Kapelonis (Codefresh)

  • There’s no standard for structures (intentionally)
  • Conway’s law applies ➑️ structure will be dictated by organizational boundaries * Certain patterns arise when it comes to repos:
    • Monorepo or
    • Polyrepo, i.e. repo per
      • app
      • team
      • environment (even though this makes promotion complicated)
  • Of course, you could always mix and match patterns.
    For example use a repo per app and and add a link to this repo to a gitops monorepo, using a git submodule or flux pointer the infra as code.


Depending on the repo pattern there are yet more options within the repo for structuring files and folder for apps, envs, teams, tenants.

These structures also depend of the nature of the team, e.g. dev/app team vs infra/platform/admin team.

Also branches could be used to organize environments, but this seems to be widely discouraged. So the recommendation is to use trunk-based development for your GitOps repos.



On top of that you might have to decide to run multiple GitOps controllers within a single cluster, running one controller to operate multiple clusters (hub-and-spoke) or one GitOps controller per Cluster (many-to-many)

And finally, specific GitOps operator provide additional facilities to organize things, e.g. ArgoCD’s apps, projects and App Of Apps pattern.

:exploding_head: So many options to choose from to create the perfect GitOps solution for your specific context. Let me summarize this with a slide from our GitOps Training



In lack of a better term, I call this the GitOps chasm, similar to the β€œimpedance missmatch” in object orientation ↔️ relational databases.

A final shameless plug: You can easily experiment with GitOps on your local machine by using our GitOps playground. It implements a combination of the repo per app and monorepo patterns with folder per stage and app (trunk-based). In a real world setting we would probably use folder per team, stage and app, like so

  β”œβ”€β”€ a-team
  β”‚   β”œβ”€β”€ staging
  β”‚   β”‚   └── application
  β”‚   β”‚       └── deployment.yaml
  β”‚   └── production
  β”‚       └── application
  β”‚           └── deployment.yaml
  └── team-B


1 Like