gh-ahmedasmar-devops-claude-skills-gitops-workflows/references/repo_patterns.md

GitOps Repository Patterns (2024-2025)

Monorepo vs Polyrepo

Monorepo Pattern

Structure:

gitops-repo/
├── apps/
│   ├── frontend/
│   ├── backend/
│   └── database/
├── infrastructure/
│   ├── ingress/
│   ├── monitoring/
│   └── secrets/
└── clusters/
    ├── dev/
    ├── staging/
    └── production/

Pros:

• Single source of truth
• Atomic changes across apps
• Easier to start with
• Simpler CI/CD

Cons:

• Scaling issues (>100 apps)
• RBAC complexity
• Large repo size
• Blast radius concerns

Best for: Startups, small teams (< 20 apps), single team ownership

Polyrepo Pattern

Structure:

infrastructure-repo/     (Platform team)
app-team-1-repo/        (Team 1)
app-team-2-repo/        (Team 2)
cluster-config-repo/    (Platform team)

Pros:

• Clear ownership boundaries
• Better RBAC (repo-level)
• Scales to 100s of apps
• Team autonomy

Cons:

• More complex setup
• Cross-repo dependencies
• Multiple CI/CD pipelines

Best for: Large orgs, multiple teams, clear separation of concerns

Common Patterns

1. Repo Per Team

• Each team has own repo
• Platform team manages infra repo
• Hub cluster manages all

2. Repo Per App

• Each app in separate repo
• Good for microservices
• Maximum autonomy

3. Hybrid (Recommended)

• Infrastructure monorepo (platform team)
• Application polyrepo (dev teams)
• Best of both worlds

App-of-Apps Pattern (ArgoCD)

Root Application:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
spec:
  source:
    repoURL: https://github.com/org/gitops
    path: apps/
  destination:
    server: https://kubernetes.default.svc

Apps Directory:

apps/
├── app1.yaml    (Application manifest)
├── app2.yaml
└── app3.yaml

Benefits: Centralized management, single sync point

Environment Structure

Option 1: Directory Per Environment

apps/
├── base/
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    ├── staging/
    └── production/

Option 2: Branch Per Environment

main branch      → production
staging branch   → staging
dev branch       → development

Don't Repeat YAML: Use Kustomize bases + overlays

Flux Repository Organization

Recommended Structure:

flux-repo/
├── clusters/
│   ├── production/
│   │   ├── flux-system/
│   │   ├── apps.yaml
│   │   └── infrastructure.yaml
│   └── staging/
├── apps/
│   └── podinfo/
│       ├── kustomization.yaml
│       └── release.yaml
└── infrastructure/
    └── sources/
        ├── gitrepositories.yaml
        └── ocirepositories.yaml

Kustomize vs Helm in GitOps

Kustomize (recommended for GitOps):

• Native Kubernetes
• Declarative patches
• No templating language

Helm (when necessary):

• Third-party charts
• Complex applications
• Need parameterization

Best Practice: Kustomize for your apps, Helm for third-party

Promotion Strategies

1. Manual PR-based

dev/ → (PR) → staging/ → (PR) → production/

2. Automated with CI

dev/ → (auto-promote on tests pass) → staging/ → (manual approval) → production/

3. Progressive with Canary

production/stable/ → canary deployment → production/all/

2024-2025 Recommendations

1. Start with monorepo, migrate to polyrepo when needed
2. Use Kustomize bases + overlays (don't repeat YAML)
3. Separate infrastructure from applications
4. Implement promotion workflows (dev → staging → prod)
5. Never commit directly to production (always PR)