Orchestrator/bahn/O2C-Harness/self-review.md

Self-Review & Pipeline-Überwachung

Code-Review vor Push

Vor dem Push den eigenen Code reviewen:

• Naming Conventions eingehalten?
• Keine TODOs oder Debug-Code?
• Tests vollständig?
• Doku aktuell?

Pipeline-Überwachung (Pflicht nach jedem Push)

Nach JEDEM git push die Pipeline überwachen mit Polling:

# Pipeline-Status abfragen (wiederholen bis nicht mehr "running")
glab ci status

# Wenn "running" → 30 Sekunden warten und erneut prüfen
sleep 30
glab ci status

# Bei "failed" → Logs des fehlgeschlagenen Jobs anzeigen
glab ci view

Polling-Schleife (so implementieren):

# Solange "running" → weiter pollen
while true; do
  STATUS=$(glab ci status 2>&1)
  echo "$STATUS"
  if echo "$STATUS" | grep -q "passed"; then
    echo "Pipeline erfolgreich!"
    break
  elif echo "$STATUS" | grep -qE "failed|canceled"; then
    echo "Pipeline fehlgeschlagen – abbrechen und fixen"
    glab ci cancel
    glab ci view
    break
  fi
  sleep 30
done

WICHTIG:

• glab ci status funktioniert OHNE --wait Flag
• NICHT die GitLab API direkt aufrufen (kein Zugriff auf Web-UI)
• Einfach glab ci status wiederholt aufrufen mit sleep 30 dazwischen

Bei Pipeline-Fehler

1. glab ci view – Fehlgeschlagenen Job identifizieren
2. Fehler analysieren
3. Fix committen
4. Erneut pushen
5. Pipeline erneut überwachen

Deployment-Stages

Branch	Umgebung	Automatisch?
Feature-Branch	Preview (Dev)	✅ Ja
main	Produktion	✅ Ja (nach Merge)

Pipeline-Fehler diagnostizieren

Logs lesen mit glab

# Jobs der Pipeline auflisten
glab api "projects/:id/pipelines/$(glab ci status 2>&1 | grep -oP '#\K[0-9]+')/jobs"

# Job-Log lesen (Job-ID aus obigem Output)
glab api "projects/:id/jobs/{job_id}/trace"

# Wenn keine Jobs vorhanden (leeres Array []):
# → Kein Runner verfügbar ODER .gitlab-ci.yml fehlerhaft

Häufige Fehler

Symptom	Ursache	Fix
Pipeline failed, keine Jobs	YAML-Fehler	.gitlab-ci.yml prüfen
Job failed: "image not found"	Falsches Docker-Image	DB Container Lib Image nutzen

Um Hilfe bitten (statt endlos loopen)

Wenn du nach 3 Versuchen ein Problem nicht lösen kannst:

1. STOPPE – nicht weiter versuchen
2. Dokumentiere das Problem klar in einer Nachricht:
   • Was du versucht hast
   • Welcher Fehler auftritt
   • Was du als Ursache vermutest
3. Schreibe in die Konsole: echo "HELP: <deine Frage>"

Beispiel:

Ich komme nicht weiter. Die Pipeline schlägt fehl:
- Symptom: Pipeline failed, keine Jobs werden gestartet
- Versucht: .gitlab-ci.yml angepasst (3x)
- Frage: Wie sieht die korrekte .gitlab-ci.yml für dieses Projekt aus?

Wann um Hilfe bitten:

• Pipeline-Fehler nach 3 Fix-Versuchen
• Zugriffsprobleme (401/403/404)
• Unklare Anforderungen
• Fehlende Credentials oder Konfiguration
• Tool funktioniert nicht wie erwartet

NICHT endlos loopen bei:

• Gleichem Fehler der sich wiederholt
• Timeout/Netzwerk-Problemen
• Fehlenden Berechtigungen

Pipeline manuell triggern

Wenn nach einem Push keine neue Pipeline startet (alter SHA in glab ci status):

# Pipeline manuell für aktuellen Branch triggern
glab ci create --ref $(git branch --show-current)

Dann erneut mit glab ci status überwachen.

Kein Runner verfügbar

Wenn Pipeline failed mit 0 Jobs oder Jobs ewig "pending" bleiben:

• Ursache: Kein Runner mit passenden Tags im Projekt
• Das ist ein Infrastruktur-Problem, kein Code-Problem
• In der MR-Beschreibung vermerken: "Pipeline benötigt Runner mit Tags: group-runner, kubernetes"
• Nicht endlos versuchen zu fixen

MR-Pipeline überwachen

• MR-Pipeline hat alle Jobs (lint, test, build, deploy)

Ablauf:

1. Push auf Feature-Branch
2. MR erstellen (glab mr create ...)
3. DANN Pipeline überwachen: glab ci status (zeigt MR-Pipeline)
4. Bei Fehler: glab ci list → Job-Logs lesen → fixen → pushen
5. MR-Pipeline startet automatisch neu nach Push

Job-Logs lesen:

# Fehlgeschlagene Jobs finden
glab ci list

# Trace eines bestimmten Jobs (non-interaktiv)
glab api "projects/:id/jobs/{job_id}/trace" | tail -50

Signal für Hilfe

Wenn du nicht weiterkommst, schreibe EXAKT dieses Format in die Shell:

echo "HELP: Pipeline failed mit 0 Jobs - wie soll die .gitlab-ci.yml aussehen?"

Das HELP: Prefix wird vom Orchestrator erkannt und signalisiert dem Benutzer im Dashboard, dass du Hilfe brauchst. Warte danach auf eine Antwort.

Pipeline-Status loggen

Beim Überwachen der Pipeline den Status in die Konsole schreiben, damit das Dashboard den Fortschritt zeigt:

echo "PROMPT: Pipeline überwachen - warte auf MR-Pipeline"
# ... polling ...
echo "PROMPT: Pipeline grün - alle Jobs bestanden"
# oder
echo "PROMPT: Pipeline fehlgeschlagen - Job lint_scm_info failed"

Fortschritt und ETA loggen

Nach jedem abgeschlossenen Arbeitsschritt den Fortschritt melden:

echo "PROGRESS: 20% - Issues angelegt, starte Implementierung (ETA: 8min)"
echo "PROGRESS: 50% - Backend fertig, starte Frontend (ETA: 5min)"
echo "PROGRESS: 70% - Tests geschrieben, starte Quality Gates (ETA: 3min)"
echo "PROGRESS: 85% - Gepusht, MR erstellt, warte auf Pipeline (ETA: 2min)"
echo "PROGRESS: 100% - Fertig"

Format: PROGRESS: {prozent}% - {was gerade passiert} (ETA: {geschätzte Restzeit})

Schätze die ETA basierend auf:

• Anzahl verbleibender Issues/Aufgaben
• Bisherige Dauer pro Schritt
• Komplexität der verbleibenden Arbeit

Referenzen in Logs

Wenn du Issues, MRs oder Pipelines erstellst/referenzierst, gib die URL oder Referenz mit an:

echo "PROMPT: Issues angelegt: #1 #2 #3 #4 in https://git.tech.rz.db.de/group/project"
echo "PROMPT: MR erstellt: https://git.tech.rz.db.de/group/project/-/merge_requests/1"
echo "PROMPT: Pipeline überwachen: https://git.tech.rz.db.de/group/project/-/pipelines/12345"

Das Dashboard macht URLs und #Issue/!MR-Referenzen automatisch klickbar.