Thomas/Homelab--Bratonein-Kontrollzentrum--Tutorial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Homelab--Bratonein-Kontroll…/Kapitel 13/Premium Rohtext.md

16 KiB
Raw Permalink Blame History

Premium – CI-Pipelines, Self-Hosted Runner & Webhooks mit Gitea

Im Free-Kapitel hast du eine stabile Gitea-Instanz eingerichtet, die deine Projekte versioniert und über HTTPS erreichbar ist.
Damit steht das Fundament für saubere Versionsverwaltung und Team-Strukturen.

Im Premium-Teil erweitern wir dieses System zu einer automatisierten Entwicklungs- und Produktionsumgebung, die eigenständig Builds, Tests oder Deployments ausführt – komplett lokal, ohne externe CI-Dienste.
Du lernst, wie Gitea mit Self-Hosted-Runnern arbeitet, wie du CI-Pipelines definierst und wie Webhooks Aktionen in anderen UCC-Systemen (z. B. n8n oder Vaultwarden) auslösen.

Ziel ist nicht mehr nur das reine Speichern von Code, sondern automatisches Ausführen, Prüfen und Verteilen – alles innerhalb deines Homelabs.

In diesem Kapitel behandeln wir:

  1. Einrichtung des Gitea-Actions-Systems
    Aktivierung der integrierten CI-Umgebung auf deiner Instanz.
    Einrichtung des ersten Self-Hosted-Runners im Container oder auf einem separaten Node.

  2. Definition einer CI-Pipeline
    Aufbau eines vollständigen Workflow-YAMLs, der Code überprüft, Dateien erstellt oder Skripte automatisch testet.
    Praxisbeispiel: Automatischer PDF-Build aus Markdown-Tutorials.

  3. Integration mit n8n und Vaultwarden
    Nutzung von Webhooks für Benachrichtigungen, Status-Monitoring und automatisches Key-Handling.
    Beispiel: Push → Webhook → n8n startet Backup oder Deployment.

  4. Erweiterte Automatisierungen (optional)
    Nutzung mehrerer Runner, paralleler Jobs und Artefakt-Uploads.
    Wie du Gitea als zentrales Automatisierungs-Backbone des UCC nutzt.

Note

Alle Schritte basieren auf der bestehenden Installation aus dem Free-Kapitel.
Die dort erstellte Gitea-Instanz bleibt unverändert – du erweiterst sie lediglich um CI- und Webhook-Funktionen.
Stelle sicher, dass dein Git-LXC aktiv und über HTTPS erreichbar ist, bevor du beginnst.

Mit diesen Erweiterungen wird Gitea zu einem vollwertigen Automations-Server –
es verwaltet Projekte, testet Änderungen, verteilt Ergebnisse und kann mit anderen Komponenten deines UCC (n8n, Vaultwarden, Nextcloud) direkt interagieren.

Gitea Actions – lokale CI/CD-Automatisierung

Mit Gitea Actions kannst du Prozesse automatisieren, die sonst manuell erledigt werden müssten – etwa das Erstellen, Testen oder Verteilen von Projekten.
Das System funktioniert ähnlich wie GitHub Actions, läuft aber vollständig lokal und benötigt keine Verbindung zu externen Diensten.
Damit bleibt deine Entwicklungs- und Produktionsumgebung komplett unter deiner Kontrolle.

Note

Gitea Actions ist seit Version 1.19 integriert.
Stelle sicher, dass dein Image aktuell ist, bevor du beginnst:

docker pull gitea/gitea:latest
docker compose up -d

Ziel dieses Abschnitts ist der Aufbau einer funktionsfähigen Actions-Umgebung mit einem eigenen Self-Hosted Runner, der deine Workflows im Homelab ausführt.

Schritt 1 – Voraussetzungen prüfen

Bevor du Actions aktivierst, überprüfe:

  • Deine Gitea-Version ist ≥ 1.19.
    In der Weboberfläche unter About oder per CLI prüfen: 
    docker exec -it gitea gitea --version
  • Der Server hat Zugriff auf lokale oder interne Runner (HTTP erreichbar).
  • Docker und Docker Compose laufen stabil.

Tip

Gitea Actions verwendet Runner, die containerisierte Jobs ausführen.
Je nach Projekt kannst du sie auf demselben Host oder in einem separaten LXC-Container betreiben.

Schritt 2 – Actions aktivieren

Actions sind standardmäßig deaktiviert.
Aktiviere sie über die Konfigurationsdatei app.ini:

nano /gitea/gitea/conf/app.ini

Füge unter [actions] den folgenden Block hinzu:

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com

Datei speichern und Container neu starten:

docker compose restart

Note

Die Angabe DEFAULT_ACTIONS_URL zeigt auf die Quelle für Standard-Workflows.
Wenn du keine externen Templates nutzen möchtest, kannst du sie auch leer lassen.

Nach dem Neustart ist im Repository-Menü der neue Tab Actions sichtbar.

👉 Screenshot geeignet: Gitea-Repository mit sichtbarem Reiter „Actions“

Schritt 3 – Self-Hosted Runner installieren

Der Runner ist das lokale Programm, das die definierten Workflows ausführt.
Er kann auf demselben LXC wie Gitea oder auf einem separaten Node laufen.

  1. Wechsle auf deinen Ziel-Container oder Host: 
    pct enter <ID>
  2. Lade den Runner: 
    mkdir -p /runner && cd /runner
curl -L -o gitea-runner https://dl.gitea.com/runner/latest/gitea-runner-linux-amd64
chmod +x gitea-runner
  3. Registrierung starten: 
    ./gitea-runner register
    Danach wirst du nach folgenden Angaben gefragt:
    • Gitea instance URL: https://git.deinedomain.tld
    • Token: generierst du im Gitea-Webinterface
      → Site Administration → Actions → Runner Tokens → Add New Token
    • Runner name: frei wählbar (z. B. ucc-runner-01)
    • Executor: shell oder docker (empfohlen)
  4. Dienst aktivieren: 
    ./gitea-runner daemon &

Tip

Wenn du Docker im Runner nutzt, kannst du Build- oder Test-Container isoliert starten.
Für einfache Automatisierungen reicht der shell-Modus.

Nach erfolgreicher Registrierung erscheint der Runner unter
Site Administration → Actions → Runners mit Status online.

👉 Screenshot geeignet: Gitea-Weboberfläche mit aktivem Runner (Status: online)

Schritt 4 – Test-Workflow anlegen

Im Repository legst du unter .gitea/workflows eine YAML-Datei an:

# Datei: .gitea/workflows/test.yml
name: Test-Workflow

on: [push]

jobs:
  check-setup:
    runs-on: self-hosted
    steps:
      - name: Repository klonen
        uses: actions/checkout@v3

      - name: Testausgabe
        run: echo "Gitea Actions läuft erfolgreich!"

Committe die Datei und pushe sie ins Repository:

git add .gitea/workflows/test.yml
git commit -m "CI: Testworkflow hinzugefügt"
git push

Note

Jeder Push löst automatisch den hinterlegten Workflow aus.
Die Ausgabe kannst du direkt im Tab Actions ansehen.

👉 Screenshot geeignet: Gitea-Workflow-Log mit erfolgreichem Joblauf

Schritt 5 – Erweiterung für reale Workflows

Beispiel: Automatischer PDF-Build aus Markdown-Tutorials (analog zum UCC-Dokumentationsprozess):

name: Build Tutorials

on: [push]

jobs:
  build-pdf:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v3
      - name: Pandoc installieren
        run: apt update && apt install -y pandoc
      - name: PDF erstellen
        run: |
          pandoc README.md -o tutorial.pdf
      - name: Artefakt speichern
        run: cp tutorial.pdf /srv/assets/projects/

Tip

Damit kannst du Markdown-Tutorials aus Gitea automatisch in dein Asset-LXC exportieren.
Gitea, Runner und Asset-System arbeiten dadurch direkt zusammen.

Schritt 2 – n8n-Workflow aufbauen

In diesem Abschnitt baust du einen voll funktionsfähigen Workflow, der automatisch reagiert, wenn in Gitea ein Push oder Release erfolgt.
Alle verwendeten Nodes sind in der kostenlosen n8n-Version enthalten.

Node 1 – Webhook

Feld Wert
HTTP Method POST
Path git-ci
Response Mode On Received
Response Data { "status": "received" }
Response Code 200

Nach dem Speichern siehst du oben die Webhook-URL, z. B.:

https://n8n.deinedomain.tld/webhook/git-ci

Diese trägst du im Gitea-Webhook ein.

Tip

Der Node funktioniert sofort nach Speichern.
Ein Test-Delivery in Gitea zeigt dir, ob n8n korrekt reagiert.

Node 2 – Set (Daten reduzieren)

Zweck: Nur die relevanten Felder aus dem JSON behalten.

  1. Verbinde den Webhook mit einem Set-Node.
  2. Öffne den Node und wähle Keep Only Set → aktivieren.
  3. Trage die folgenden Felder ein:
Name Ausdruck
repository ={{ $json["repository"]["full_name"] }}
event `={{ $json["action"]
ref ={{ $json["ref"] }}
user ={{ $json["sender"]["login"] }}

Speichern → Execute Node klicken → du solltest ein kompaktes JSON mit vier Feldern erhalten.

Node 3 – Switch (Ereignis prüfen)

  1. Füge einen Switch-Node hinzu.
  2. Verbinde ihn mit dem Set-Node.
  3. Im Feld Value to Compare: 
    {{$json["event"]}}
  4. Füge drei Cases hinzu:
Case Name Wert
Push push
Release release
Workflow workflow_run

Jetzt entscheidet der Node automatisch, welcher Zweig ausgeführt wird.

Node 4 – SSH (Befehl ausführen)

Dieser Node startet auf einem entfernten Server oder Container einen definierten Befehl.
Beispiel für automatische Aktualisierung eines Projekts bei Push.

Feld Wert
Host 10.0.0.20
Port 22
Username deploy
Password / SSH Key entsprechend eintragen
Command cd /srv/project && git pull && systemctl restart app

Speichern → über den Switch-Zweig Push verbinden.

Node 5 – HTTP Request (Deployment oder Benachrichtigung)

Beispiel für automatisches Triggern eines Deployments bei Release.

Feld Wert
Method POST
URL https://ucc-api.deinedomain.tld/deploy
Body Content Type JSON
JSON/RAW Parameters {"repo":"={{$json.repository}}","ref":"={{$json.ref}}"}

Verbinde diesen Node mit dem Switch-Zweig Release.

Node 6 – Discord (optional)

Zum Senden von Statusmeldungen oder Benachrichtigungen.
Nutze den kostenlosen Standard-Discord-Node.

Feld Wert
Resource Message
Operation Create
Channel ID 123456789012345678
Text =📦 Neues Event in {{$json.repository}} ({{$json.event}})

Verbinde diesen Node mit allen Switch-Zweigen, falls du immer informiert werden möchtest.

👉 Screenshot geeignet: kompletter n8n-Workflow von Webhook → Set → Switch → SSH/HTTP/Discord

Note

Alle hier genutzten Nodes sind Standard-Bestandteil der n8n Community Edition.
Keine Cloud-Verbindung, keine Zusatzmodule nötig.
Du kannst den gesamten Workflow exportieren, sichern und auf jedem n8n-System importieren.

Vaultwarden-Integration

Damit deine Automatisierung sicher bleibt, verwaltet Vaultwarden alle Zugangsdaten, Tokens und Secrets zentral.
So liegen Passwörter und API-Keys nicht im Klartext in n8n oder Gitea, sondern werden nur bei Bedarf abgerufen.
Das schützt dein System vor versehentlichen Leaks oder unbefugtem Zugriff.

Note

Für diese Integration genügt der Standard-Vaultwarden-Container aus dem UCC-System.
Es wird keine Erweiterung oder API-Plugin benötigt – die REST-API ist in jeder Installation verfügbar.

Ziel

Du verknüpfst n8n mit Vaultwarden, um:

  • das Webhook-Secret aus Gitea sicher zu speichern
  • Zugriffsdaten für SSH oder API-Calls nur zur Laufzeit bereitzustellen
  • CI-Prozesse automatisiert und trotzdem verschlüsselt auszuführen

Secret in Vaultwarden anlegen

  1. Öffne die Weboberfläche von Vaultwarden.
  2. Klicke auf + Add Item → Typ Secure Note.
  3. Trage folgende Werte ein:
Feld Beispiel
Name GITEA_WEBHOOK_SECRET
Folder CI/CD
Notes dein Webhook-Secret aus Gitea
Favorite optional aktivieren
  1. Speichern.
    Vaultwarden verschlüsselt das Secret automatisch.
    Du kannst es später per API abrufen, ohne es jemals im Klartext zu sehen.

👉 Screenshot geeignet: Vaultwarden-Interface mit angelegtem Secret GITEA_WEBHOOK_SECRET

API-Token für n8n erstellen

Damit n8n auf Vaultwarden zugreifen darf, benötigt es ein Zugriffstoken.

  1. In Vaultwarden → Settings → API Keys
  2. Auf Generate New Key klicken.
  3. Einen Namen vergeben, z. B. n8n-access.
  4. Optional Ablaufdatum setzen.
  5. Key kopieren (er wird nur einmal angezeigt).

Tip

Der API-Key sollte nur Lesezugriff haben, wenn dein Vault mehrere Benutzer oder Secrets enthält.

Secret aus Vaultwarden in n8n abrufen

In n8n fügst du vor sicherheitsrelevanten Schritten (z. B. SSH oder API-Call) einen HTTP Request Node ein, der das Secret abfragt.

Feld Wert
Method GET
URL https://vault.deinedomain.tld/api/secrets/GITEA_WEBHOOK_SECRET
Response Format JSON
Authentication Header Auth
Header Name Authorization
Header Value Bearer <API-Key>

Nach Ausführen erhältst du eine Antwort ähnlich:

{
  "data": {
    "id": "123abc",
    "type": "note",
    "name": "GITEA_WEBHOOK_SECRET",
    "notes": "meinSuperSecret123"
  }
}

Im nächsten Node kannst du den Wert dynamisch verwenden:

={{ $json["data"]["notes"] }}

Tip

Verwende dieses Secret z. B. im Webhook-Verification-Schritt, SSH-Node oder API-Aufruf.
So bleibt der Schlüssel außerhalb des Workflows gespeichert und kann zentral rotiert werden.

Secret-Rotation automatisieren (optional)

Vaultwarden unterstützt über die API das Ersetzen von Werten.
Damit kannst du in regelmäßigen Abständen neue Tokens oder Passwörter generieren und direkt im Vault ablegen.

In n8n kombinierst du dazu:

  • Cron Node (z. B. alle 30 Tage)
  • HTTP Request (PUT) mit neuem Tokenwert
  • Discord Node oder Email Node zur Benachrichtigung

Beispiel für API-Request zur Aktualisierung:

Feld Wert
Method PUT
URL https://vault.deinedomain.tld/api/secrets/GITEA_WEBHOOK_SECRET
Body Content Type JSON
JSON Body {"notes":"{{ $json.newToken }}"}
Header Auth Bearer <API-Key>

Important

Automatische Token-Rotation ist optional, aber sehr empfehlenswert, wenn dein System dauerhaft online ist.
So stellst du sicher, dass alte oder kompromittierte Tokens keine Gefahr darstellen.

👉 Screenshot geeignet: n8n-Workflow mit HTTP-Node zum Secret-Abruf vor einem SSH- oder API-Schritt

Mit dieser Integration bleiben alle Zugangsdaten dezentral verwaltet, verschlüsselt gespeichert und jederzeit austauschbar.
Vaultwarden wird so zur zentralen Sicherheitsinstanz deiner gesamten Automatisierung im UCC.

Abschluss

Mit der Erweiterung aus diesem Premium-Kapitel hast du aus einer einfachen Git-Verwaltung eine vollwertige Automatisierungsplattform gemacht.
Gitea arbeitet nun nicht nur als Code- und Dokumentenarchiv, sondern als aktiver Bestandteil deiner Produktions- und Streaming-Infrastruktur.
Durch Actions, n8n und Vaultwarden ist ein geschlossenes System entstanden, das Builds, Backups und Deployments selbstständig steuert – komplett lokal und unabhängig von externen CI-Diensten.

Die Kombination aus Self-Hosted Runnern und n8n-Webhooks ermöglicht dir flexible Workflows:
Markdown-Dateien können automatisch in PDFs umgewandelt, Projektdaten gesichert oder Statusmeldungen an Discord gesendet werden.
Vaultwarden sorgt dabei dafür, dass sensible Daten nie im Klartext auftauchen und jederzeit zentral ausgetauscht werden können.

Note

Mit dieser Integration hast du die Grundlage geschaffen, um alle Projekte im UCC miteinander zu verknüpfen:
Git speichert und versioniert, n8n führt Aktionen aus, Vaultwarden verwaltet die Secrets –
zusammen bilden sie eine vollständig automatisierte Entwicklungs- und Betriebsumgebung.

Ein korrekt eingerichtetes CI-System mit Gitea bietet dir:

  • Lokale, cloudfreie CI/CD-Pipelines
  • Self-Hosted Runner für flexible Aufgabenverteilung
  • Direkte Anbindung an n8n für Benachrichtigung, Backup oder Deployment
  • Sichere Geheimnisverwaltung durch Vaultwarden
  • Vollständige Kontrolle über Build- und Release-Prozesse

👉 Screenshot geeignet: Gitea Actions-Tab mit laufendem Workflow und verknüpftem Runner

Mit Abschluss dieses Kapitels hast du eine robuste, skalierbare und sichere Basis geschaffen,
auf der künftige Premium-Kapitel wie automatische Dokumentverteilung, Build-Pipelines für UCC-Projekte oder integrierte Testumgebungen direkt aufbauen können.
Gitea wird so zu einem der zentralen Werkzeuge im UCC – effizient, transparent und vollständig unter deiner Kontrolle.