Course contentsShow
← Software Engineering
Lesson 1499 of 1,93343. Infrastructure as CodeFree lesson

Repository Structure for GitOps

Learn best practices for organizing GitOps repositories: separating config from code, environment branches, and app-of-apps patterns.

Repository Structure for GitOps

What you'll learn: How to organize your GitOps repositories for clarity, maintainability, and safe multi-environment deployments.

The Core Challenge

When adopting GitOps, one of the first questions is: "Where does everything go?" Poor repository organization leads to tangled configs, risky changes, and confused teammates. Good structure makes reviews easy, rollbacks safe, and environments clear.

Key Organizational Patterns

Separating Config from Code

Keep application source code separate from deployment manifests. Your app repo should contain business logic; your GitOps repo contains Kubernetes YAML, Helm values, or Terraform configs. This separation lets different teams own different concerns and prevents accidental production changes during feature development.

Think of it like separating recipes (code) from kitchen layouts (infrastructure)—they evolve independently.

Environment Branches or Directories

You can organize environments in two ways:

  • Branch-per-environment: main branch for production, staging branch for staging. Promotions happen via pull requests between branches.
  • Directory-per-environment: Single branch with /environments/dev, /environments/staging, /environments/prod folders.

Directories are simpler and make cross-environment comparisons easier. Branches provide stronger isolation but complicate side-by-side audits.

The App-of-Apps Pattern

Instead of one massive YAML file, create a root application that references child applications. Each microservice or component gets its own folder with manifests. The root app orchestrates everything, making it easy to add/remove services without touching unrelated configs.

This is like a master playlist that references individual songs—you manage the collection without rewriting every track.

Key Takeaway: Structure GitOps repos with clear config/code separation, consistent environment organization (prefer directories), and an app-of-apps pattern for managing multiple services—this keeps your infrastructure code reviewable, testable, and safe.