From 43a06eae4daae19ccc2e82310e3b4d2423b52e96 Mon Sep 17 00:00:00 2001
From: Michael Schiemer <kontakt@michaelschiemer.de>
Date: Sat, 8 Nov 2025 17:25:22 +0100
Subject: [PATCH] docs: Add documentation and playbooks for fixing Gitea runner
 configuration

- Add FIX_RUNNER_CONFIG.md with manual steps to re-register runner
- Add fix-gitea-runner-config.yml to diagnose runner issues
- Add register-gitea-runner.yml to re-register runner via Ansible
- Fixes issue where runner falls back to GitHub on 504 errors
---
 .../playbooks/fix-gitea-runner-config.yml     |  6 +-
 deployment/gitea-runner/FIX_RUNNER_CONFIG.md  | 92 +++++++++++++++++++
 2 files changed, 95 insertions(+), 3 deletions(-)
 create mode 100644 deployment/gitea-runner/FIX_RUNNER_CONFIG.md

diff --git a/deployment/ansible/playbooks/fix-gitea-runner-config.yml b/deployment/ansible/playbooks/fix-gitea-runner-config.yml
index 845ba92d..1058786d 100644
--- a/deployment/ansible/playbooks/fix-gitea-runner-config.yml
+++ b/deployment/ansible/playbooks/fix-gitea-runner-config.yml
@@ -126,9 +126,9 @@
 
     - name: Backup existing .runner file
       copy:
-      src: "{{ gitea_runner_path }}/data/.runner"
-      dest: "{{ gitea_runner_path }}/data/.runner.backup.{{ ansible_date_time.epoch }}"
-      remote_src: yes
+        src: "{{ gitea_runner_path }}/data/.runner"
+        dest: "{{ gitea_runner_path }}/data/.runner.backup.{{ ansible_date_time.epoch }}"
+        remote_src: yes
       when: 
         - runner_file_exists.stat.exists
         - runner_needs_reregistration | bool
diff --git a/deployment/gitea-runner/FIX_RUNNER_CONFIG.md b/deployment/gitea-runner/FIX_RUNNER_CONFIG.md
new file mode 100644
index 00000000..99e8f37f
--- /dev/null
+++ b/deployment/gitea-runner/FIX_RUNNER_CONFIG.md
@@ -0,0 +1,92 @@
+# Gitea Runner Konfiguration korrigieren
+
+## Problem
+
+Der Gitea Runner verwendet gemischte URLs (GitHub + Gitea) und fällt bei 504-Fehlern auf GitHub zurück, was zu Timeouts führt.
+
+## Lösung: Runner neu registrieren
+
+### Schritt 1: Runner stoppen
+
+```bash
+cd deployment/gitea-runner
+docker compose stop gitea-runner
+```
+
+### Schritt 2: Backup erstellen und .runner Datei entfernen
+
+```bash
+# Backup erstellen
+cp data/.runner data/.runner.backup.$(date +%s)
+
+# .runner Datei entfernen (wird bei neuer Registration neu erstellt)
+rm -f data/.runner
+```
+
+### Schritt 3: Runner starten
+
+```bash
+docker compose up -d gitea-runner
+```
+
+### Schritt 4: Runner neu registrieren
+
+```bash
+# .env Datei laden
+source .env
+
+# Runner registrieren (nur mit korrekter Gitea-URL)
+docker compose exec -T gitea-runner act_runner register \
+  --instance "${GITEA_INSTANCE_URL}" \
+  --token "${GITEA_RUNNER_REGISTRATION_TOKEN}" \
+  --name "${GITEA_RUNNER_NAME}" \
+  --labels "${GITEA_RUNNER_LABELS}"
+```
+
+**Wichtig**: Bei der Aufforderung "Runner is already registered, overwrite local config? [y/N]" mit `y` antworten.
+
+### Schritt 5: Verifikation
+
+1. **Prüfe .runner Datei:**
+   ```bash
+   cat data/.runner | grep -E "(address|instance)"
+   ```
+   Sollte nur `https://git.michaelschiemer.de` enthalten, keine GitHub-URLs.
+
+2. **Prüfe Runner-Logs:**
+   ```bash
+   docker compose logs gitea-runner --tail=50 | grep -E "(github|instance|declare)"
+   ```
+   Sollte `declare successfully` zeigen und keine GitHub-URLs mehr enthalten.
+
+3. **Prüfe in Gitea UI:**
+   - Gehe zu: https://git.michaelschiemer.de/admin/actions/runners
+   - Runner sollte als "Online" angezeigt werden
+
+## Automatisierung
+
+Falls der Runner automatisch neu registriert werden soll:
+
+```bash
+cd deployment/gitea-runner
+./unregister.sh  # Falls vorhanden
+./register.sh    # Neu registrieren
+```
+
+## Troubleshooting
+
+**Runner registriert sich nicht:**
+- Prüfe, ob Gitea erreichbar ist: `curl https://git.michaelschiemer.de/api/healthz`
+- Prüfe, ob der Registration Token noch gültig ist
+- Prüfe Runner-Logs: `docker compose logs gitea-runner`
+
+**Runner verwendet immer noch GitHub:**
+- Stelle sicher, dass die `.runner` Datei nur die korrekte Gitea-URL enthält
+- Prüfe, ob es mehrere Runner-Instanzen gibt: `docker ps | grep runner`
+- Prüfe Workflow-Definitionen auf GitHub-URLs
+
+**504 Gateway Timeout:**
+- Prüfe Gitea-Container: `docker logs gitea`
+- Prüfe Traefik-Logs: `docker logs traefik`
+- Stelle sicher, dass Gitea nicht überlastet ist
+