INSIGHT-MVP/docs/FORGEJO_SETUP.md

Forgejo Setup - Anleitung fuer den Git-Server

Ziel: Forgejo so konfigurieren, dass CI/CD Pipelines (Forgejo Actions) automatisch laufen und Docker Images in die integrierte Container Registry gepusht werden.

---

1. Voraussetzungen pruefen

1.1 Forgejo Actions aktiviert?

Forgejo Actions ist seit Forgejo 1.21+ verfuegbar, muss aber in der Server-Konfiguration aktiviert sein.

In der Forgejo-Konfiguration (app.ini auf dem Git-Server) pruefen:

# /etc/forgejo/app.ini (oder wo Forgejo installiert ist)

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org

Falls nicht vorhanden: Eintrag hinzufuegen und Forgejo neustarten.

sudo systemctl restart forgejo

1.2 Container Registry aktiviert?

Die Registry muss ebenfalls in app.ini aktiviert sein:

[packages]
ENABLED = true

---

2. Forgejo Actions Runner einrichten

Forgejo Actions braucht einen Runner (vergleichbar mit GitHub Actions Self-Hosted Runner). Der Runner fuehrt die CI/CD-Jobs aus.

2.1 Runner auf dem Git-Server installieren

# Runner-Binary herunterladen (aktuelle Version pruefen auf:
# https://code.forgejo.org/forgejo/runner/releases)

# Beispiel fuer Linux x86_64:
wget https://code.forgejo.org/forgejo/runner/releases/download/v4.0.0/forgejo-runner-4.0.0-linux-amd64
chmod +x forgejo-runner-4.0.0-linux-amd64
sudo mv forgejo-runner-4.0.0-linux-amd64 /usr/local/bin/forgejo-runner

2.2 Runner registrieren

Zuerst ein Registration Token in Forgejo generieren:

1. Forgejo Web-UI oeffnen: https://git.xinion.lan
2. Site Administration > Runners (oben rechts Zahnrad-Icon)
3. Oder: Repository > Settings > Actions > Runners
4. Klick auf "Create new Runner" oder "Registration Token"
5. Token kopieren

Dann auf dem Server den Runner registrieren:

# Runner registrieren (interaktiv)
forgejo-runner register \
  --instance https://git.xinion.lan \
  --token <DEIN-REGISTRATION-TOKEN> \
  --name insight-runner \
  --labels ubuntu-latest:docker://node:20

# Alternativ: non-interaktiv
forgejo-runner register --no-interactive \
  --instance https://git.xinion.lan \
  --token <DEIN-REGISTRATION-TOKEN> \
  --name insight-runner \
  --labels "ubuntu-latest:docker://node:20,docker:docker://docker:latest"

2.3 Runner als Systemd-Service einrichten

# Service-Datei erstellen
sudo tee /etc/systemd/system/forgejo-runner.service > /dev/null << 'UNIT'
[Unit]
Description=Forgejo Actions Runner
After=docker.service

[Service]
Type=simple
User=forgejo-runner
WorkingDirectory=/opt/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
UNIT

# User und Verzeichnis anlegen
sudo useradd -r -s /bin/false forgejo-runner
sudo mkdir -p /opt/forgejo-runner
sudo chown forgejo-runner:forgejo-runner /opt/forgejo-runner

# Docker-Zugriff fuer den Runner
sudo usermod -aG docker forgejo-runner

# Service starten
sudo systemctl daemon-reload
sudo systemctl enable forgejo-runner
sudo systemctl start forgejo-runner

# Status pruefen
sudo systemctl status forgejo-runner

2.4 Pruefen ob Runner aktiv ist

In Forgejo Web-UI:

• Site Administration > Runners
• Der Runner insight-runner sollte mit Status "Online" erscheinen

---

3. Repository-Einstellungen

3.1 Actions fuer das Repository aktivieren

1. Repository oeffnen: https://git.xinion.lan/gitadmin/INSIGHT-MVP
2. Settings > Repository
3. Unter "Actions": Haken setzen bei "Enable Repository Actions"
4. Speichern

3.2 Repository Secrets anlegen

Die CI/CD-Pipeline braucht Secrets fuer den Server-Zugang.

1. Settings > Actions > Secrets
2. Folgende Secrets anlegen:

Secret Name	Wert	Zweck
SSH_DEPLOY_KEY	Inhalt von .keys/cicd_ed25519 (Private Key)	SSH-Zugriff auf Server
DEPLOY_HOST	IP-Adresse von insight-dev-01	Server-Adresse
DEPLOY_USER	deploy	SSH-User auf dem Server
REGISTRY_USER	Forgejo-Username (z.B. gitadmin)	Container Registry Login
REGISTRY_PASSWORD	Forgejo-Passwort oder Access Token	Container Registry Login

SSH Key als Secret hinterlegen

Den kompletten Inhalt des Private Keys kopieren:

# Auf dem MacBook ausfuehren:
cat .keys/cicd_ed25519

Den gesamten Output (inkl. -----BEGIN OPENSSH PRIVATE KEY----- und -----END OPENSSH PRIVATE KEY-----) in das Secret-Feld einfuegen.

Forgejo Access Token erstellen (fuer Registry)

Statt Passwort empfehlen wir einen Access Token:

1. Forgejo Web-UI > Profil (oben rechts) > Settings > Applications
2. Generate New Token
3. Name: insight-registry
4. Berechtigungen: write:package (oder package Scope)
5. Token kopieren und als REGISTRY_PASSWORD Secret anlegen

3.3 Branch Protection einrichten

1. Settings > Branches
2. Add Branch Protection Rule

Fuer main:

• Branch name pattern: main
• Enable push: Deaktiviert (nur via Merge)
• Required approvals: 1
• Status checks must pass: Aktiviert

Fuer develop:

• Branch name pattern: develop
• Enable push: Deaktiviert (nur via Merge)
• Required approvals: 1
• Status checks must pass: Aktiviert

---

4. Container Registry testen

4.1 Vom MacBook aus testen

# In die Forgejo Registry einloggen
docker login git.xinion.lan -u <FORGEJO-USERNAME>
# Passwort oder Access Token eingeben

# Test-Image taggen und pushen
docker pull hello-world
docker tag hello-world git.xinion.lan/gitadmin/insight-test:latest
docker push git.xinion.lan/gitadmin/insight-test:latest

# Aufraumen
docker rmi git.xinion.lan/gitadmin/insight-test:latest

4.2 In Forgejo pruefen

1. Repository > Packages Tab
2. Das insight-test Image sollte sichtbar sein
3. Nach dem Test kann es geloescht werden

---

5. Checkliste

Bitte alle Punkte abarbeiten und abhaken:

• app.ini: [actions] ENABLED = true gesetzt
• app.ini: [packages] ENABLED = true gesetzt
• Forgejo neugestartet nach Config-Aenderung
• Forgejo Runner installiert und registriert
• Runner laeuft als Systemd-Service und ist "Online"
• Repository Actions aktiviert (Settings > Repository)
• Secret SSH_DEPLOY_KEY angelegt (CI/CD Private Key)
• Secret DEPLOY_HOST angelegt (Server-IP)
• Secret DEPLOY_USER angelegt (deploy)
• Secret REGISTRY_USER angelegt (Forgejo Username)
• Secret REGISTRY_PASSWORD angelegt (Access Token)
• Branch Protection fuer main eingerichtet
• Branch Protection fuer develop eingerichtet
• Container Registry getestet (docker push/pull funktioniert)

---

6. Haeufige Probleme

Runner startet nicht

# Logs pruefen
sudo journalctl -u forgejo-runner -f

# Hat der Runner Docker-Zugriff?
sudo -u forgejo-runner docker ps

Actions werden nicht getriggert

• Ist Actions im Repository aktiviert? (Settings > Repository)
• Liegt die Workflow-Datei unter .forgejo/workflows/?
• Ist der Runner online? (Site Administration > Runners)

Registry Push schlaegt fehl

# Login testen
docker login git.xinion.lan

# Ist die Registry aktiviert?
# In app.ini: [packages] ENABLED = true

Branch Protection blockiert Push

• Korrekt! Main und Develop sind geschuetzt.
• Feature-Branches erstellen: git checkout -b feature/mein-feature
• Push auf Feature-Branch, dann Pull Request erstellen