# Workflow — GitOps / No-Drift Regeln

Dieses Dokument definiert den verbindlichen Arbeitsablauf für Änderungen an der Homelab-Infrastruktur.

---

## Ziel

Es darf **keine dauerhafte Abweichung** zwischen:

- Git-Repository
- Portainer-Stacks
- laufenden Docker-Containern
- Host-Konfiguration

geben.

**Grundsatz:**  
> Git ist die einzige Quelle der Wahrheit.

---

## Die wichtigste Regel

Änderungen werden immer in dieser Reihenfolge durchgeführt:

1. **Änderung im Repository**
2. **Commit**
3. **Push**
4. **Deploy über Portainer**
5. **Test**
6. **Dokumentation aktualisieren**

---

## Verbotene Arbeitsweise

Folgende Dinge sind grundsätzlich zu vermeiden:

- Änderungen direkt im Portainer Web Editor
- Änderungen direkt per `docker run`
- Änderungen an laufenden Containern ohne Repo-Anpassung
- spontane Host-Hotfixes ohne Nachdokumentation
- Secrets im Git-Repository
- mehrere Services gleichzeitig migrieren

---

## Erlaubte Arbeitsweise

Erlaubt und gewünscht sind:

- Änderungen an Compose-Dateien im Git-Repo
- Commit + Push vor jedem Deploy
- Portainer nur als Deployment- und Monitoring-Werkzeug
- Host-Hotfixes nur im Ausnahmefall
- sofortige Nachpflege im Repo, wenn ein Hotfix nötig war
- Migration immer nur **ein Service pro Sprint**

---

## No-Drift-Prinzip

### Definition

**Configuration Drift** liegt vor, wenn der reale Zustand vom Git-Zustand abweicht.

Beispiele:
- laufender Container wurde manuell verändert
- Portainer-Stack entspricht nicht mehr dem Repo
- Host-Dateien wurden angepasst, aber nicht dokumentiert
- Traefik dynamic config wurde lokal geändert, aber Git weiß nichts davon

### Regel

Wenn Drift erkannt wird, gilt:

1. Drift **nicht ignorieren**
2. Drift **sofort benennen**
3. entscheiden:
   - Repo an Realität anpassen  
   **oder**
   - Realität an Repo zurückführen
4. erst danach weiterarbeiten

---

## Ausnahmefall: Hotfix auf dem Host

Manchmal ist ein Live-Hotfix nötig, um einen Dienst sofort wieder lauffähig zu machen.

Das ist erlaubt, aber nur unter diesen Bedingungen:

1. Hotfix nur wenn der Dienst sonst nicht funktioniert
2. Änderung sofort dokumentieren
3. Änderung danach ins Git-Modell überführen
4. kein stiller Dauerzustand

### Pflicht bei Hotfixes

Nach jedem Hotfix müssen diese Fragen beantwortet werden:

- Was wurde geändert?
- Wo wurde es geändert?
- Warum war es nötig?
- Muss diese Änderung ins Repo übernommen werden?
- Ist ein Rollback dokumentiert?

---

## Portainer-Regeln

Portainer ist in diesem Setup:

- Deployment-Werkzeug
- Monitoring-Werkzeug
- Log-/Status-Werkzeug

Portainer ist **nicht** die Quelle der Wahrheit.

### Deshalb gilt

- Git-Stacks nicht im Portainer Editor ändern
- Stack-Konfiguration nur im Repository anpassen
- Portainer nur zum Deploy/Redeploy nutzen
- Wenn Portainer und Git voneinander abweichen, gewinnt Git

---

## Secrets-Regeln

- Secrets liegen niemals im Repository
- Secrets liegen unter `/mnt/user/appdata/secrets/`
- Secrets werden über Datei-Mounts oder `_FILE` Variablen eingebunden
- Rechte: `chmod 600`
- Secret-Namen und Pfade werden in `docs/SECRETS_MAP.md` dokumentiert

---

## Dokumentationspflicht

Nach jeder erfolgreichen Migration oder relevanten Änderung müssen diese Dateien geprüft werden:

- `docs/MIGRATION_LOG.md`
- `docs/SECRETS_MAP.md`
- `docs/ROLLBACK.md`
- `HOMELAB_ARCHITECTURE_MASTER_V2.md` (falls Architektur betroffen)

---

## Sprint-Regel

Jede Migration wird als Sprint behandelt.

Ein Sprint umfasst immer:

1. Ist-Zustand prüfen
2. Zielzustand definieren
3. Compose-Datei im Repo anpassen
4. Commit + Push
5. Deploy über Portainer
6. Test
7. Dokumentation aktualisieren
8. Sprint abschließen

### Wichtig

> Nie mehrere kritische Dienste gleichzeitig ändern.

---

## Rollback-Regel

Jede Änderung muss rückrollbar sein.

Vor jedem Deploy muss klar sein:

- wie der letzte funktionierende Zustand aussieht
- welcher Commit der letzte stabile Stand ist
- ob Datenpfade unverändert bleiben
- wie der Dienst im Fehlerfall zurückgenommen wird

Wenn Rollback nicht klar ist, wird nicht deployt.

---

## Umgang mit Legacy-Konfiguration

Legacy-Konfigurationen außerhalb des Repos gelten als Risiko.

Beispiele:
- alte Traefik dynamic files
- manuell erzeugte Host-Konfigurationen
- frühere Docker-/Dockerman-Einzelcontainer

### Regel

Legacy-Bestand muss:

1. identifiziert
2. dokumentiert
3. schrittweise entfernt oder ins Repo überführt

werden.

---

## Arbeitsregel für KI-Assistenten

Wenn mit einer KI gearbeitet wird, gilt immer:

> Lies zuerst:
> 1. `HOMELAB_ARCHITECTURE_MASTER_V2.md`
> 2. `docs/WORKFLOW.md`
> 3. die betroffene Compose-Datei
> 4. ggf. `docs/MIGRATION_LOG.md`

Erst danach dürfen Änderungen vorgeschlagen werden.

---

## Merksatz

> Erst Git, dann Deploy.  
> Erst Wahrheit, dann Aktion.  
> Kein Drift, kein Chaos.