187 lines
4.3 KiB
Markdown
187 lines
4.3 KiB
Markdown
# 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
|