Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท GitOps Principles

Git Repository Layouts for GitOps: Mono-repo, Poly-repo, Folders vs Branches

Choose a Git repository layout for GitOps: app code versus config repos, mono-repo versus many repos, folders versus branches per environment, and a clean directory structure for Argo CD.

Before you create dozens of Applications, decide where their YAML lives. The repository layout affects who can change what, how reviews work, how fast Argo CD renders and how painful promotion is. There is no single right answer, but there are patterns with known trade-offs and a few mistakes that are costly to undo.

No cluster is needed for this lesson. The runnable blocks are stand-ins: a layout validator that checks a list of paths against conventions, and a tiny generator for an environment tree.

Rule one: separate app code from config

Keep the source code of an application and its deployment manifests in different repositories (or at least different directories with separate triggers). Reasons:

  • Every code commit would otherwise trigger a manifest change, and every CI bump of an image tag (a commit by a bot) would pollute the code history.
  • Access differs: developers may write code, while only a release process or ops team may change production config.
  • Argo CD refreshes on repository changes. A busy code repo makes unrelated apps re-render.
  • A config repo has a clean audit log of what was deployed, and when.
flowchart LR
  App["app repo: source code and Dockerfile"] --> CI["CI pipeline"]
  CI -->|"image tag commit"| Cfg[("config repo: manifests")]
  Cfg --> Argo["Argo CD"]

The CI pipeline is the only bridge between the code repo and the config repo.

Mono-repo or many repos?

Layout Strengths Weaknesses
One config repo for everything One place to search, atomic cross-app changes, simple credentials Noisy history, coarse permissions, large repo for the repo server
One config repo per team Team autonomy, matching permissions More repositories to register, shared pieces get duplicated
One config repo per application Strongest isolation Many repos, hard to see the whole estate

A common middle path: a platform repo for cluster add-ons (ingress controller, monitoring) and one config repo per team or product.

Environments: folders, not branches

You can express "dev, staging, production" as branches or as folders. Branch-per-environment looks natural, but it causes trouble: promotions become merges with conflicts, branches drift in ways that are hard to spot, and a diff between environments is a diff between histories rather than between files.

Folder per environment on one branch (usually main) is the widely recommended approach:

TEXT
config-repo/
โ”œโ”€โ”€ apps/
โ”‚   โ””โ”€โ”€ shop/
โ”‚       โ”œโ”€โ”€ base/                  # shared manifests
โ”‚       โ”‚   โ”œโ”€โ”€ deployment.yaml
โ”‚       โ”‚   โ”œโ”€โ”€ service.yaml
โ”‚       โ”‚   โ””โ”€โ”€ kustomization.yaml
โ”‚       โ””โ”€โ”€ overlays/
โ”‚           โ”œโ”€โ”€ dev/kustomization.yaml
โ”‚           โ”œโ”€โ”€ staging/kustomization.yaml
โ”‚           โ””โ”€โ”€ production/kustomization.yaml
โ”œโ”€โ”€ platform/
โ”‚   โ”œโ”€โ”€ ingress-nginx/
โ”‚   โ””โ”€โ”€ monitoring/
โ””โ”€โ”€ clusters/
    โ”œโ”€โ”€ dev/apps.yaml              # Application manifests for dev
    โ””โ”€โ”€ production/apps.yaml

Promotion is a normal pull request that changes a file under overlays/production, so the diff is exactly what will change. Branches can still be useful for short-lived things such as preview environments from pull requests, or a single release-1.x branch for a long-supported version.

Where do the Application manifests live?

The Applications themselves are YAML, so they belong in Git too. Typical choices:

  • a clusters/<name>/ directory holding one Application per workload, applied by a single root Application (the app-of-apps pattern, covered in a later chapter), or
  • an ApplicationSet that generates them from the folder structure.

Stand-in: validate a layout

Paste your own file list into this checker. It enforces a few conventions: environments as folders, no secrets in plain text, manifests in expected places.

JS Stand-in: layout validator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: generate an environment tree

The second stand-in prints the tree for a list of apps and environments, which is handy when planning a repo.

JS Stand-in: tree generator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Other practical advice

  • Pin what you deploy: image tags or digests, chart versions and Git tags, never latest.
  • Keep generated files out unless you intend to review them; rendering at sync time (Helm, Kustomize) avoids committing thousands of lines. Some teams commit rendered manifests deliberately so reviewers see the final YAML (the "rendered manifests" pattern).
  • Use CODEOWNERS and branch protection so changes under production/ need the right reviewers.
  • Keep directories flat enough to read; Argo CD can render recursively if asked, but one Application per directory is the clearest mapping.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why separate application source code from deployment config?

    Separate repos give separate permissions, cleaner history and avoid image-tag commits polluting the code history.
  2. 2. Which is the recommended way to model environments?

    Folders make promotion a normal reviewable diff and avoid branch drift.
  3. 3. What is the biggest downside of one giant config repo?

    Everything in one repo means broad access and noisy commits, though it is simple.
  4. 4. Where should the CI pipeline's final step write?

    CI hands over by committing the new version to the config repo; Argo CD does the delivery.

Summary

  • Keep app code and deployment config in separate repositories or at least separate paths.
  • Choose mono-repo, per-team or per-app config repos based on permissions and scale.
  • Prefer folders per environment over branches per environment.
  • Store Application manifests in Git as well, under something like clusters/<name>/.
  • Pin versions, avoid plain-text secrets, and use CODEOWNERS for production paths.

Next: Declarative vs Imperative