ADR-010: Multi-Repo statt Monorepo¶
| Feld | Wert |
|---|---|
| Status | accepted |
| Datum | 2026-03-21 |
| Betrifft | alle |
Kontext¶
Das Homelab-Ökosystem besteht aus fünf Repositories (homeserver, homelab-external, claude-pi, docker-images, novabrands-mgmt) plus einem zentralen Dokumentationsrepo. Es wurde evaluiert, ob die Homelab-Kern-Repos (homeserver, homelab-external, claude-pi) in ein Monorepo zusammengelegt werden sollten — inklusive Dokumentation und eventuell zukünftiger Home-Assistant-Konfigurationen.
Die zentrale Frage: Überwiegen die Vorteile atomarer Änderungen und zentraler Verwaltung die Nachteile der Deployment-Kopplung?
Entscheidung¶
Die bestehende Multi-Repo-Struktur wird beibehalten. Jedes Projekt behält sein eigenes Repository. Die zentrale Dokumentation (homelab-documentation) dient als "Wissens-Monorepo" — eine Single Source of Truth für Dokumentation, ADRs und RFCs, ohne die Konfigurationsdateien selbst zusammenzulegen.
Der Hauptgrund: Die Repos werden direkt auf den Zielmaschinen ausgecheckt und deployt. Ein Monorepo würde bedeuten, dass jede Maschine das gesamte Repo clonen muss und Logik braucht, um nur den eigenen Teil zu nutzen.
Alternativen¶
| Option | Ergebnis |
|---|---|
| Volles Monorepo (alle 5 + Doku) | Maximale Kopplung, Novabrands passt thematisch nicht rein, CI/CD-Komplexität durch Path-Filter, Secrets-Isolation geht verloren. |
| Homelab-Kern-Monorepo (NUC + Hetzner + Pi + Doku) | Atomare Änderungen möglich, aber Deployment-Kopplung: jede Maschine müsste das gesamte Repo clonen. Sparse Checkout oder Deployment-Skripte als Workaround nötig. |
| Multi-Repo mit zentraler Doku (gewählt) | Jedes Repo direkt deploybar auf der Zielmaschine. Dokumentation und Architekturentscheidungen zentral. Querverweise über Links, ADRs und RFCs. |
Konsequenzen¶
Positiv:
- Repos bleiben direkt auf den Zielmaschinen deploybar (
git pull && docker compose up) - Secrets bleiben pro Repo isoliert
- CI/CD bleibt einfach — keine Path-Filter nötig
- Git-History pro Projekt sauber und fokussiert
- Unterschiedliche Deployment-Zyklen verursachen keinen Noise
Negativ:
- Änderungen über Projektgrenzen erfordern mehrere PRs in mehreren Repos
- Renovate, CLAUDE.md und CI-Konfiguration müssen pro Repo gepflegt werden
- Suche über alle Projekte erfordert mehrere Repos (oder die zentrale Doku)
- Risiko, dass Doku und Configs auseinanderlaufen — mitigiert durch RFCs und Reviews