Self hosted Runner in der Praxis

GitHub managed Runner sind praktisch, aber nicht für jeden Anwendungsfall geeignet. Vielleicht benötigen Sie spezielle Hardware, möchten Compliance-Anforderungen erfüllen oder auf interne Ressourcen zugreifen, ohne komplexe Netzwerk-Setups. Hier kommen selbst-gehostete Runner ins Spiel: Sie betreiben die Runner-Infrastruktur auf Ihrer eigenen Hardware oder in Ihrer Cloud-Umgebung.

Dieses Kapitel führt Sie Schritt für Schritt durch die praktische Arbeit mit selbst-gehosteten Runnern – von der Installation über die Organisation mit Labels und Gruppen bis hin zu fortgeschrittenen Themen wie Container-Anpassung und Monitoring.

16.1 Wichtige Sicherheitsüberlegung

Bevor wir einsteigen, ein kritischer Hinweis: GitHub empfiehlt selbst-gehostete Runner ausschließlich für private Repositories. Der Grund ist simpel, aber gravierend: Bei öffentlichen Repositories kann jeder einen Fork erstellen und über einen Pull Request Code auf Ihrem Runner ausführen lassen. Ein böswilliger Akteur könnte Ihre Infrastruktur kompromittieren, Daten stehlen oder Ihren Runner für andere Zwecke missbrauchen.

Wenn Sie selbst-gehostete Runner einsetzen, stellen Sie sicher, dass: - Die Repositories privat sind - Sie die Zugriffe über Runner-Gruppen kontrollieren - Der Runner in einer isolierten Umgebung läuft - Sensible Daten und Credentials geschützt sind

16.2 Runner hinzufügen

Die Installation eines selbst-gehosteten Runners erfolgt auf drei Ebenen: Repository, Organisation oder Enterprise. Die Wahl hängt davon ab, wie Sie den Runner nutzen möchten.

Ebene	Zugriff	Typischer Einsatz
Repository	Nur dieses Repository	Dedizierte Hardware für ein Projekt
Organisation	Alle oder ausgewählte Repositories	Geteilte Runner für Teams
Enterprise	Mehrere Organisationen	Zentrale Runner-Infrastruktur

16.2.1 Runner auf Repository-Ebene hinzufügen

Navigieren Sie zum Repository, öffnen Sie Settings → Actions → Runners und klicken Sie auf New self-hosted runner. GitHub zeigt Ihnen nun plattformspezifische Installationsanweisungen.

Das Interface zeigt Download-Links und Konfigurationsschritte für Ihr Betriebssystem. Auf einem Linux-System sieht der Prozess typischerweise so aus:

# 1. Runner-Anwendung herunterladen
mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-x64-2.311.0.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-2.311.0.tar.gz
tar xzf ./actions-runner-linux-x64-2.311.0.tar.gz

# 2. Runner konfigurieren
./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO \
  --token AUTHENTICATION_TOKEN

# 3. Runner starten
./run.sh

Das config.sh-Script fragt interaktiv einige Details ab: - Runner-Name (wird in der UI angezeigt) - Runner-Gruppe (falls vorhanden) - Labels (mehr dazu später) - Arbeitsverzeichnis

Wichtig: Der --token-Parameter enthält ein zeitlich begrenztes Token, das GitHub automatisch generiert. Es ist nur eine Stunde gültig. Wenn Sie die Konfiguration später durchführen möchten, müssen Sie ein neues Token über die GitHub-UI generieren.

16.2.2 Runner auf Organisations-Ebene

Für Organisations-Runner folgen Sie demselben Prozess, starten aber bei Organization Settings → Actions → Runners → New self-hosted runner. Der Vorteil: Sie können den Runner-Zugriff über Policies steuern und ihn mehreren Repositories zur Verfügung stellen.

./config.sh --url https://github.com/YOUR-ORG \
  --token TOKEN \
  --runnergroup production-runners

Die Runner-Gruppe muss bereits existieren, sonst schlägt die Konfiguration fehl. Wir behandeln Gruppen gleich ausführlicher.

16.3 Runner als Systemdienst konfigurieren

Wenn Sie ./run.sh manuell starten, läuft der Runner nur, solange Ihre Shell-Session aktiv ist. Für produktive Umgebungen möchten Sie, dass der Runner automatisch startet und im Hintergrund läuft. Auf Linux-Systemen mit systemd ist das elegant gelöst:

# Runner-Dienst installieren
sudo ./svc.sh install

# Optional: Als spezifischer Benutzer installieren
sudo ./svc.sh install runner-user

# Dienst starten
sudo ./svc.sh start

# Status prüfen
sudo ./svc.sh status

# Dienst stoppen
sudo ./svc.sh stop

# Dienst deinstallieren
sudo ./svc.sh uninstall

Der systemd-Service wird unter /etc/systemd/system/actions.runner.ORG-REPO.RUNNERNAME.service erstellt. Sie können den Status auch direkt über systemctl abfragen:

systemctl status actions.runner.myorg-myrepo.runner01.service

Debian/Ubuntu-Spezialfall: Auf Debian-basierten Systemen kann das Tool needrestart nach Updates automatisch Dienste neu starten – auch Ihren Runner, potenziell mitten in einem Job. Um das zu verhindern:

echo '$nrconf{override_rc}{qr(^actions\.runner\..+\.service$)} = 0;' | \
  sudo tee /etc/needrestart/conf.d/actions_runner_services.conf

16.4 Labels: Runner organisieren und gezielt ansprechen

Labels sind der Mechanismus, über den Sie in Workflows bestimmte Runner auswählen. Jeder selbst-gehostete Runner erhält automatisch diese Standard-Labels:

Ein Linux-Runner auf ARM64-Hardware hat also standardmäßig die Labels: self-hosted, linux, ARM64.

16.4.1 Workflows auf selbst-gehostete Runner lenken

jobs:
  build:
    runs-on: [self-hosted, linux, ARM64]
    steps:
      - uses: actions/checkout@v4
      - run: make build

Dieser Job läuft nur auf Runnern, die alle drei Labels besitzen. Die Label-Auswahl ist konjunktiv – ein UND, kein ODER.

16.4.2 Benutzerdefinierte Labels erstellen

Standard-Labels reichen oft nicht aus. Vielleicht haben Sie Runner mit unterschiedlicher Hardware-Ausstattung, verschiedenen Netzwerk-Zonen oder speziellen Software-Installationen. Dafür erstellen Sie benutzerdefinierte Labels.

Das Label wird dem Runner zugewiesen. Unbenutzte Labels (die keinem Runner zugeordnet sind) werden automatisch nach 24 Stunden gelöscht.

# Einzelnes Label
./config.sh --url REPO_URL --token TOKEN --labels gpu

# Mehrere Labels (kommagetrennt)
./config.sh --url REPO_URL --token TOKEN --labels gpu,high-memory,nvme-storage

Wichtig: Wenn Sie Standard-Labels explizit angeben (z.B. --labels linux), überschreibt GitHub die automatische Erkennung nicht. Das heißt, Sie können einen Windows-Runner nicht durch --labels linux zu einem Linux-Runner machen. GitHub prüft das nicht – es wird einfach als zusätzliches Label behandelt.

16.4.3 Labels in Workflows kombinieren

Ein praktisches Beispiel: Sie haben GPU-Runner für Machine Learning und wollen sicherstellen, dass Jobs auf Linux-Systemen mit GPU laufen:

jobs:
  train-model:
    runs-on: [self-hosted, linux, gpu]
    steps:
      - name: Train Model
        run: python train.py --use-gpu

jobs:
  deploy-staging:
    runs-on: [self-hosted, linux, staging]
    steps:
      - run: ./deploy.sh staging

  deploy-production:
    runs-on: [self-hosted, linux, production]
    steps:
      - run: ./deploy.sh production

16.4.4 Standard-Labels deaktivieren

Für spezielle Anwendungsfälle können Sie die automatischen Standard-Labels deaktivieren:

./config.sh --url REPO_URL --token TOKEN --no-default-labels

Der Runner erhält dann nur die Labels, die Sie explizit angeben. Das ist selten nötig, kann aber sinnvoll sein, wenn Sie eine sehr granulare Kontrolle über die Label-Struktur benötigen.

16.5 Runner-Gruppen: Zugriffskontrolle und Organisation

Runner-Gruppen sind ein mächtiges Werkzeug für Organisationen, um Runner zu organisieren und den Zugriff zu kontrollieren. Jede Organisation hat eine Default-Gruppe, in die neue Runner automatisch eingefügt werden. Mit GitHub Team oder höheren Plänen können Sie zusätzliche Gruppen erstellen.

16.5.1 Warum Runner-Gruppen?

Stellen Sie sich vor, Sie haben: - Runner in verschiedenen Netzwerk-Zonen (DMZ, Internal, Production) - Runner mit unterschiedlichen Sicherheitsstufen - Runner für verschiedene Teams oder Projekte

Mit Gruppen können Sie festlegen, welche Repositories auf welche Runner zugreifen dürfen.

16.5.2 Runner-Gruppe erstellen

Navigieren Sie zu Organization Settings → Actions → Runner groups und klicken Sie auf New runner group.

1. Gruppen-Name: Beschreibend, z.B. “Production Runners” oder “GPU Cluster”

2. Repository-Zugriff: Welche Repositories dürfen Runner aus dieser Gruppe nutzen? - Alle Repositories - Ausgewählte Repositories - Nur private Repositories (Standard)

Das ist die Zugriffskontrolle: Auch wenn ein Workflow einen Runner mit passenden Labels anfordert, kann er ihn nur nutzen, wenn das Repository Zugriff auf die Runner-Gruppe hat.

16.5.3 Runner einer Gruppe zuweisen

./config.sh --url ORG_URL --token TOKEN --runnergroup production-runners

16.5.4 Runner-Gruppen in Workflows verwenden

jobs:
  deploy:
    runs-on:
      group: production-runners
    steps:
      - run: ./deploy.sh

Das wählt einen beliebigen verfügbaren Runner aus der Gruppe “production-runners”. Sie können Gruppen auch mit Labels kombinieren:

jobs:
  gpu-training:
    runs-on:
      group: ml-runners
      labels: [self-hosted, linux, gpu]
    steps:
      - run: python train.py

Hier muss der Runner sowohl zur Gruppe “ml-runners” gehören als auch alle drei Labels besitzen.

16.6 Verfügbare Runner und aktuelle Jobs einsehen

Navigieren Sie zu Settings → Actions → Runners. Sie sehen eine Liste aller Runner mit: - Name - Status (Idle, Active, Offline) - Labels - Gruppe - Betriebssystem

Klicken Sie oben auf “Self-hosted”, um nur selbst-gehostete Runner zu sehen (filtert GitHub-gehostete Runner aus).

Klicken Sie auf den Eintrag für Ihre Runner-Gruppe. Im Abschnitt “Active Jobs” sehen Sie alle derzeit laufenden Jobs mit: - Job-Name - Repository - Laufzeit

Das ist wertvoll beim Debugging: Wenn ein Runner als “Active” angezeigt wird, aber nichts in den Logs erscheint, können Sie hier sehen, ob tatsächlich ein Job läuft.

Status	Bedeutung
Idle	Verbunden und bereit für Jobs
Active	Führt gerade einen Job aus
Offline	Nicht verbunden – Maschine aus, Service gestoppt oder Netzwerkproblem

16.7 Hooks: Skripts vor und nach Jobs ausführen

Ein leistungsfähiges Feature selbst-gehosteter Runner: Sie können Lifecycle-Hooks definieren – Skripts, die automatisch vor oder nach einem Job ausgeführt werden.

16.7.1 Anwendungsfälle

16.7.2 Hook-Typen

16.7.3 Hooks konfigurieren

#!/bin/bash
# cleanup.sh - Aufräumen vor jedem Job

echo "Cleaning up workspace..."
rm -rf /tmp/runner-workspace/*
docker container prune -f
echo "Cleanup complete"
exit 0

Wichtig: Der Exitcode bestimmt, ob der Job fortfährt: - exit 0: Success – Job startet - Jeder andere Exitcode: Job wird als fehlgeschlagen markiert

Speichern Sie das Script außerhalb des Runner-Verzeichnisses, z.B. in /opt/runner-hooks/cleanup.sh, und machen Sie es ausführbar:

chmod +x /opt/runner-hooks/cleanup.sh

# /home/runner/actions-runner/.env
ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner-hooks/cleanup.sh

sudo systemctl edit actions.runner.myorg-myrepo.runner01.service

[Service]
Environment="ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner-hooks/cleanup.sh"

Nach Änderungen an .env oder der Service-Konfiguration müssen Sie den Runner neu starten:

sudo ./svc.sh stop
sudo ./svc.sh start

16.7.4 Hooks in Workflow-Logs sehen

16.7.5 Timeout-Handling

Es gibt kein eingebautes Timeout für Hooks. Wenn Ihr Script hängt, blockiert es den Job indefinit. Implementieren Sie daher eigene Timeouts in Ihren Scripts:

#!/bin/bash
# cleanup.sh mit Timeout

timeout 60 docker container prune -f || {
  echo "Cleanup timed out after 60 seconds"
  exit 1
}

16.8 Container-Anpassung für fortgeschrittene Szenarien

Wenn Ihre Workflows Container nutzen (container:-Direktive), startet der Runner standardmäßig Docker-Container. Für spezielle Anforderungen – etwa Kubernetes-Orchestrierung oder Podman statt Docker – können Sie den Container-Lifecycle anpassen.

Achtung: Dieses Feature ist experimentell und nur für Linux-Runner verfügbar. Root-Zugriff ist nicht erforderlich.

16.8.1 Die vier Container-Befehle

Befehl	Zeitpunkt	Aufgabe
`prepare_job`	Job-Start	Container pullen, Netzwerk erstellen, Container starten
`cleanup_job`	Job-Ende	Container stoppen und löschen
`run_container_step`	Pro Container-Action	Container-Action ausführen
`run_script_step`	Pro Script-Step	Script im Container ausführen

Jeder Befehl wird als JSON-Datei definiert. GitHub hat ein Beispiel-Repository mit Implementierungen für Docker und Kubernetes: actions/runner-container-hooks.

16.8.2 Beispiel: Kubernetes statt Docker

cd /opt
git clone https://github.com/actions/runner-container-hooks.git
cd runner-container-hooks

npm install
npm run bootstrap
npm run build-all

Das erzeugt packages/k8s/dist/index.js – das Anpassungs-Script für Kubernetes. Aktivieren Sie es:

# In der Runner .env-Datei
ACTIONS_RUNNER_CONTAINER_HOOKS=/opt/runner-container-hooks/packages/k8s/dist/index.js
ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER=true

Die zweite Variable (REQUIRE_JOB_CONTAINER) erzwingt, dass Jobs Container nutzen müssen. Jobs ohne container:-Direktive werden abgelehnt.

Nach Runner-Neustart verwendet GitHub Actions nun Kubernetes-Pods statt Docker-Container für containerbasierte Jobs.

16.8.3 Wann ist das nützlich?

Für die meisten Anwendungsfälle ist die Standard-Docker-Integration ausreichend. Container-Anpassung ist ein Advanced-Feature für spezielle Infrastruktur-Anforderungen.

16.9 Monitoring und Problembehandlung

Selbst-gehostete Runner benötigen Wartung. Hier die wichtigsten Diagnose- und Monitoring-Techniken.

16.9.1 Runner-Status prüfen

# Status des systemd-Service
sudo systemctl status actions.runner.myorg-myrepo.runner01.service

# Oder via svc.sh
sudo ./svc.sh status

In der GitHub-UI sehen Sie den Status unter Settings → Actions → Runners. Ein “Offline”-Runner bedeutet: - Die Maschine ist heruntergefahren - Der Runner-Service läuft nicht - Netzwerk-Konnektivität ist unterbrochen

16.9.2 Netzwerk-Konnektivität testen

Der Runner muss mit verschiedenen GitHub-Services kommunizieren. Testen Sie das mit dem eingebauten Check:

./config.sh --check --url REPO_URL --pat TOKEN

Ersetzen Sie TOKEN durch ein Personal Access Token mit workflow-Scope. Das Script testet alle erforderlichen Verbindungen:

Schlägt ein Test fehl, finden Sie Details in den Log-Dateien unter _diag/. Der exakte Pfad wird in der Ausgabe angezeigt.

Selbst-gehostete Runner benötigen ausgehenden HTTPS-Zugriff (Port 443) zu: - github.com - api.github.com - *.actions.githubusercontent.com - *.pkg.github.com

16.9.3 TLS-Zertifikat-Probleme

In Unternehmensumgebungen mit TLS-Interception kann die Zertifikat-Validierung fehlschlagen. Nur für Tests können Sie die Validierung deaktivieren:

export GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY=1
./config.sh --url REPO_URL --token TOKEN
./run.sh

Warnung: Das ist ein Sicherheitsrisiko. Produktiv sollten Sie das GitHub-Zertifikat (oder das Ihrer TLS-Inspection-Infrastruktur) zum System-Truststore hinzufügen.

16.9.4 Log-Dateien analysieren

Runner-Logs (Runner_*.log): Zeigen den Lifecycle der Runner-Anwendung – Starts, Verbindungen, Fehler.

Worker-Logs (Worker_*.log): Details zur Job-Ausführung – was in jedem Step passiert.

Wichtig bei kurzlebigen Runnern: Diese Logs werden lokal gespeichert. Wenn Ihre Runner nach jedem Job zerstört werden (Auto-Scaling), gehen die Logs verloren. Leiten Sie sie an ein zentrales Logging-System weiter (Syslog, ELK, CloudWatch, etc.).

16.9.5 journalctl für systemd-Services

sudo journalctl -u actions.runner.myorg-myrepo.runner01.service -f

Das ist wertvoll für Live-Debugging: Sie sehen sofort, wenn Jobs starten oder fehlschlagen.

16.9.6 Automatische Updates überwachen

Die Runner-Anwendung aktualisiert sich selbst automatisch. Diesen Prozess sollten Sie überwachen, da veraltete Runner keine Jobs mehr annehmen.

Wichtig: Das Runner-Update erfolgt automatisch. Sie müssen keine manuellen Updates durchführen. Aber: Das Betriebssystem und andere Software (Docker, etc.) müssen Sie selbst aktuell halten.

16.9.7 Docker-spezifische Probleme

sudo systemctl is-active docker.service

# Finden Sie den Runner-User heraus
sudo systemctl show -p User actions.runner.myorg-myrepo.runner01.service

# Prüfen Sie die Docker-Gruppe
groups runner-user

sudo usermod -aG docker runner-user

Wenn Actions mit Fehlern wie “Input required and not supplied” abbrechen, kann das an einer inkompatiblen Docker-Installation liegen. Snap-basierte Docker-Installationen sind problematisch:

which docker
# /snap/bin/docker  <- Problematisch

16.10 Runner entfernen

16.10.1 Temporäres Deaktivieren

Manchmal möchten Sie einen Runner nur vorübergehend offline nehmen – für Wartung, Updates oder Tests. Einfach den Service stoppen:

sudo ./svc.sh stop

Der Runner erscheint in der GitHub-UI als “Offline”, bleibt aber registriert. Nach sudo ./svc.sh start nimmt er Jobs wieder an.

16.10.2 Permanentes Entfernen

Navigieren Sie zu Settings → Actions → Runners, klicken Sie auf den Runner und dann auf “Remove”. GitHub zeigt Ihnen einen Befehl:

./config.sh remove --token REMOVAL_TOKEN

Führen Sie diesen auf dem Runner aus. Das: - Deregistriert den Runner bei GitHub - Löscht lokale Konfigurationsdateien - Entfernt systemd-Services (falls als Service installiert)

Klicken Sie in der UI auf “Force remove this runner”. Das entfernt den Runner aus GitHub, aber lokale Dateien bleiben auf der Maschine.

Runner werden automatisch entfernt, wenn sie sich zu lange nicht verbinden: - Standard-Runner: 14 Tage Inaktivität - Kurzlebige Runner: 1 Tag Inaktivität - JIT-Runner (Just-in-Time): Sofort nach dem Job oder bei Nicht-Ausführung

16.10.3 Runner für Wiederverwendung vorbereiten

Wenn Sie einen Runner-Computer für einen neuen Runner nutzen wollen, ohne die Anwendung neu herunterzuladen:

rm .runner

Das löscht die Registrierungsdatei. Sie können dann ./config.sh erneut ausführen, um den Runner neu zu registrieren.

16.11 Best Practices für den Produktivbetrieb

Abschließend einige bewährte Strategien für selbst-gehostete Runner in Produktion:

Isolation: Führen Sie Runner in isolierten VMs oder Containern aus. Ein kompromittierter Runner sollte keinen Zugriff auf sensible Produktionssysteme haben.

Monitoring: Integrieren Sie Runner-Logs in Ihr zentrales Monitoring. Alerting bei Offline-Runnern oder fehlgeschlagenen Jobs ist essenziell.

Skalierung: Nutzen Sie Auto-Scaling für dynamische Workloads. Tools wie der Kubernetes Operator oder Terraform-Module helfen dabei.

Regelmäßige Updates: Während die Runner-Anwendung sich selbst aktualisiert, müssen Sie OS-Updates und Dependencies manuell pflegen. Automatisieren Sie das.

Backup der Logs: Bei kurzlebigen Runnern (z.B. Spot-Instances) gehen Logs bei Beendigung verloren. Leiten Sie sie extern weiter.

Labels konsistent verwenden: Etablieren Sie eine Namenskonvention für Labels. Dokumentieren Sie, welche Labels was bedeuten. Das verhindert Verwirrung in großen Teams.

Gruppen für Zugriffskontrolle: Nutzen Sie Runner-Gruppen konsequent, um zu kontrollieren, welche Repositories auf welche Runner zugreifen. Das ist eine wichtige Sicherheitsebene.

Selbst-gehostete Runner geben Ihnen volle Kontrolle über die Ausführungsumgebung – zu dem Preis, dass Sie diese Umgebung selbst verwalten müssen. Mit den richtigen Werkzeugen und Prozessen ist das jedoch gut handhabbar und ermöglicht Workflows, die mit GitHub-gehosteten Runnern nicht möglich wären.

16 Self hosted Runner in der Praxis