michaelschiemer/deployment/WORKFLOW-TROUBLESHOOTING.md

Workflow Troubleshooting Guide

Problem: Workflows brechen zwischendurch ab

Mögliche Ursachen

1. Actions werden nicht geladen

Symptom: Workflow startet, aber Actions wie actions/checkout@v4 schlagen fehl

Lösung: Prüfe Gitea Konfiguration:

docker exec gitea cat /data/gitea/conf/app.ini | grep -A 3 '[actions]'

Sollte enthalten:

[actions]
ENABLED = true
# Do NOT set DEFAULT_ACTIONS_URL - it will automatically use Gitea's own instance
# Setting DEFAULT_ACTIONS_URL to custom URLs is no longer supported by Gitea

2. Timeouts bei langen Steps

Symptom: Workflow läuft eine Zeit, dann Timeout

Lösung: Timeout in Runner Config erhöhen:

# deployment/gitea-runner/config.yaml
runner:
  timeout: 6h  # Erhöhe von 3h auf 6h

Dann Runner neu starten:

cd deployment/gitea-runner
docker compose restart gitea-runner

3. Docker Buildx Probleme

Symptom: Build Step schlägt fehl oder bricht ab

Lösung: Prüfe, ob Buildx richtig läuft. Alternativ: Direktes Docker Build verwenden.

4. Gitea-Variablen (früher GitHub-kompatibel)

Symptom: ${{ github.sha }} ist leer oder falsch

Lösung: Gitea Actions unterstützt github.* Variablen für Kompatibilität, aber gitea.* ist die native Variante.

Test: Prüfe in Workflow-Logs, welche Variablen verfügbar sind:

- name: Debug variables
  run: |
    echo "GITHUB_SHA: ${{ github.sha }}"
    echo "GITEA_SHA: ${{ gitea.sha }}"
    echo "RUNNER_OS: ${{ runner.os }}"

5. Secrets fehlen oder sind falsch

Symptom: Registry Login oder SSH schlägt fehl

Lösung: Prüfe Secrets in Gitea:

• Repository → Settings → Secrets
• Alle benötigten Secrets sollten vorhanden sein:
  • REGISTRY_USER
  • REGISTRY_PASSWORD
  • SSH_PRIVATE_KEY
  • ANSIBLE_VAULT_PASSWORD (falls verwendet)

Debugging-Schritte

1. Workflow-Logs analysieren

In Gitea UI:

1. Gehe zu Actions → Fehlgeschlagener Workflow
2. Klicke auf fehlgeschlagene Step
3. Prüfe Logs für Fehlermeldungen
4. Suche nach:
   • error
   • timeout
   • failed
   • exit code

2. Runner-Logs prüfen

cd deployment/gitea-runner
docker compose logs gitea-runner --tail=100 | grep -E "(error|failed|timeout)"

3. Runner Status prüfen

In Gitea: https://git.michaelschiemer.de/admin/actions/runners

Prüfe:

• Status sollte "Idle" oder "Running" sein
• Letzte Aktivität sollte kürzlich sein
• Keine Fehler-Meldungen

Häufige Fehler und Fixes

Problem: "Action not found"

Fehler: Error: Action 'actions/checkout@v4' not found

Fix:

1. Prüfe DEFAULT_ACTIONS_URL in Gitea config
2. Stelle sicher, dass Internet-Zugriff vom Runner vorhanden ist
3. Gitea neu starten: docker compose restart gitea

Problem: "Timeout"

Fehler: timeout: job exceeded maximum duration

Fix:

1. Erhöhe Timeout in config.yaml
2. Oder teile Workflow in kleinere Jobs auf

Problem: "Docker build failed"

Fehler: Docker Build schlägt fehl

Fix:

1. Prüfe docker-dind Container läuft
2. Prüfe Registry-Zugriff
3. Prüfe Registry-Credentials

Problem: "SSH connection failed"

Fehler: Ansible Deployment kann nicht zum Server verbinden

Fix:

1. Prüfe SSH_PRIVATE_KEY Secret ist korrekt
2. Prüfe SSH-Key hat richtige Berechtigungen
3. Prüfe Firewall erlaubt Verbindung

Workflow optimieren

Reduziere Workflow-Zeit

1. Cache verwenden:

   - uses: actions/cache@v3
     with:
       path: vendor
       key: composer-${{ hashFiles('composer.lock') }}
   

2. Parallel Jobs:

   jobs:
     test:
       # ...
     build:
       # ...
     # Beide können parallel laufen
   

3. Conditional Steps:

   - name: Skip on docs change
     if: contains(github.event.head_commit.message, '[skip ci]')
     run: exit 0
   

Nächste Schritte

1. Identifiziere genaue Abbruch-Stelle:

   • In welchem Step bricht es ab?
   • Welche Fehlermeldung erscheint?

2. Prüfe Logs:

   • Workflow-Logs in Gitea UI
   • Runner-Logs: docker compose logs gitea-runner

3. Teste einzelne Steps:

   • Führe Steps manuell aus
   • Isoliere das Problem

4. Workflow vereinfachen:

   • Reduziere auf minimalen Test-Workflow
   • Füge Steps schrittweise hinzu