Skip to content

ADR-003: Use a Single GitHub Monorepo

Status

Accepted

Date

2026-03-07

Context

GitOps repositories can be structured as a monorepo (all clusters, infrastructure, and apps in one repo) or as a multi-repo (separate repos per team/service/environment). The right choice depends on team size, access control requirements, and operational complexity.

Decision

Use a single GitHub monorepo (HomeKube) with directory-based separation:

clusters/     — Flux Kustomization objects (what gets deployed where)
infrastructure/ — Platform services (ingress, cert-manager)
observability/  — Monitoring stack
apps/         — Application workloads
docs/         — ADRs and documentation

Alternatives Considered

Structure Reason Not Chosen
Multi-repo (infra + apps) Adds complexity (cross-repo Flux sources, separate PRs for infra vs app), overkill for a single-person sandbox
Flat single directory No separation of concerns, becomes unmaintainable as the project grows
Helm umbrella chart Tightly couples all components; harder to evolve independently; doesn't teach Kustomize overlay patterns

Consequences

Positive

  • Single place to understand the entire system
  • Simple Flux bootstrap: --path=clusters/local scans one repo
  • Easy to cross-reference infrastructure and app changes in the same commit/PR
  • Natural evolution path: directories can become separate repos later without architectural change (just update sourceRef in Flux Kustomization objects)

Negative

  • As the project grows, repository size increases
  • No fine-grained access control between infra and apps (all contributors see everything)
  • Branch protection rules apply uniformly — cannot restrict infrastructure changes differently from app changes

Trade-offs

Simplicity and full visibility are prioritised for a learning context. Multi-repo can be adopted in Phase 4+ when CI/CD automation and team boundaries require it.