# 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:
```bash
docker exec gitea cat /data/gitea/conf/app.ini | grep -A 3 '[actions]'
```

Sollte enthalten:
```ini
[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:
```yaml
# deployment/gitea-runner/config.yaml
runner:
  timeout: 6h  # Erhöhe von 3h auf 6h
```

Dann Runner neu starten:
```bash
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:
```yaml
- 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

```bash
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:**
   ```yaml
   - uses: actions/cache@v3
     with:
       path: vendor
       key: composer-${{ hashFiles('composer.lock') }}
   ```

2. **Parallel Jobs:**
   ```yaml
   jobs:
     test:
       # ...
     build:
       # ...
     # Beide können parallel laufen
   ```

3. **Conditional Steps:**
   ```yaml
   - 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