lawgit/GITEA_ACTIONS_SETUP.md

# Gitea Actions Runner Einrichtung

Diese Anleitung erklärt, wie du den Gitea Actions Runner für automatische Gesetzes-Updates einrichtest.

## Voraussetzungen

- Gitea-Version >= 1.19 (Actions-Unterstützung)
- SSH-Zugriff auf den Strato V-Server
- Root-Rechte für Service-Setup
- Python 3.11+ auf dem Runner-System

## 1. Gitea-Version prüfen

```bash
# In Gitea einloggen und unter /admin prüfen
# Oder via SSH auf dem Server:
gitea --version
```

## 2. Act Runner installieren

### Download und Installation

```bash
# Aktuelle Version von https://gitea.com/gitea/act_runner/releases herunterladen
cd /opt  # oder ein anderes Verzeichnis deiner Wahl
wget -O act_runner https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64
chmod +x act_runner

# Architektur prüfen (falls nicht amd64):
# uname -m  # zeigt Architektur (x86_64, arm64, etc.)
```

### Runner registrieren

1. Gehe in Gitea zu: `https://git.coded.law/admin/actions/runners`
2. Klicke auf "Neuen Runner hinzufügen"
3. Kopiere den Token (z.B. `GITEA_RUNNER_TOKEN=abc123...`)

```bash
# Runner registrieren
./act_runner register \
  --instance https://git.coded.law \
  --token $GITEA_RUNNER_TOKEN \
  --name lawgit-runner \
  --labels ubuntu-latest:docker://node:20-bullseye

# Labels anpassen:
# ubuntu-latest:docker://node:20-bullseye  # Für Docker-basierte Runner
# ubuntu-latest  # Für native Runner
```

### Systemd-Service einrichten

Erstelle `/etc/systemd/system/act-runner.service`:

```ini
[Unit]
Description=Gitea Act Runner
After=network.target

[Service]
Type=simple
ExecStart=/opt/act_runner daemon
WorkingDirectory=/opt
User=git  # Oder ein dedizierter User (nicht root!)
Restart=always
RestartSec=5

# Umgebungsvariablen (optional)
Environment="GITEA_RUNNER_NAME=lawgit-runner"

[Install]
WantedBy=multi-user.target
```

**Wichtig**: Erstelle einen dedizierten User statt root zu verwenden:

```bash
# User erstellen
sudo useradd -m -s /bin/bash gitea-runner
sudo mkdir -p /opt
sudo chown gitea-runner:gitea-runner /opt/act_runner

# Service aktivieren
sudo systemctl daemon-reload
sudo systemctl start act-runner
sudo systemctl enable act-runner
```

### Status prüfen

```bash
# Service-Status
sudo systemctl status act-runner

# Logs anzeigen
sudo journalctl -u act-runner -f

# Runner in Gitea prüfen
# Gehe zu: https://git.coded.law/admin/actions/runners
```

## 3. Workflow testen

1. Gehe zu: `https://git.coded.law/username/lawgit/actions`
2. Klicke auf "Update Laws from RSS"
3. Klicke auf "Run workflow" (workflow_dispatch)
4. Prüfe die Logs

## 4. Workflow-Datei

Die Workflow-Datei befindet sich in: `.gitea/workflows/update-laws.yaml`

Sie führt folgende Schritte aus:
1. Repository auschecken
2. Python 3.11 einrichten
3. Dependencies installieren (`requirements.txt`)
4. `update_laws.py` ausführen (lädt neue Gesetze)
5. `xml_to_markdown.py --prod` ausführen (konvertiert zu Markdown)
6. Änderungen committen und pushen

## 5. Fehlerbehandlung

### Runner startet nicht

```bash
# Logs prüfen
sudo journalctl -u act-runner -n 50

# Berechtigungen prüfen
ls -la /opt/act_runner
sudo chmod +x /opt/act_runner
```

### Workflow schlägt fehl

1. Prüfe die Workflow-Logs in Gitea
2. Prüfe ob Python-Dependencies installiert sind
3. Prüfe ob `update_laws.py` und `xml_to_markdown.py` im Repo sind
4. Prüfe Git-Berechtigungen (Runner braucht Push-Rechte)

### Rate-Limits

Falls Downloads fehlschlagen, füge Delays hinzu:

```python
import time
time.sleep(1)  # Zwischen Downloads
```

## 6. Sicherheit

- **Nicht als root laufen**: Erstelle einen dedizierten User
- **HTTPS**: Stelle sicher, dass Gitea über HTTPS läuft
- **Firewall**: Beschränke Zugriff auf Runner-Ports falls nötig
- **Secrets**: Verwende Gitea Secrets für sensible Daten

## 7. Monitoring

### Logs überwachen

```bash
# Systemd-Logs
sudo journalctl -u act-runner -f

# Gitea-Logs
tail -f /var/lib/gitea/log/gitea.log
```

### Workflow-Historie

- Gitea UI: `https://git.coded.law/username/lawgit/actions`
- Zeigt alle Workflow-Ausführungen und deren Status

## 8. Anpassungen

### Cron-Zeit ändern

Bearbeite `.gitea/workflows/update-laws.yaml`:

```yaml
schedule:
  - cron: '0 2 * * *'  # Täglich um 02:00 UTC
```

Cron-Format: `Minute Stunde Tag Monat Wochentag`

### Andere Trigger

```yaml
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: '0 2 * * *'
```

## Troubleshooting

### Runner erscheint nicht in Gitea

- Prüfe ob Token korrekt ist
- Prüfe Netzwerkverbindung zwischen Runner und Gitea
- Prüfe Firewall-Regeln

### Workflow wird nicht ausgeführt

- Prüfe ob Workflow-Datei im richtigen Branch ist
- Prüfe Cron-Syntax
- Prüfe Runner-Labels (müssen mit `runs-on` übereinstimmen)

### Git-Push schlägt fehl

- Prüfe ob Runner Git-Berechtigungen hat
- Prüfe ob Remote korrekt konfiguriert ist
- Prüfe ob Branch-Name korrekt ist (`main` vs `master`)