Selbst gehostete GitHub-Runner: Linux-Setup, Docker und Kubernetes

Ein selbst gehosteter GitHub-Runner führt Jobs für GitHub Actions auf einer von Ihnen bereitgestellten Maschine aus und verwendet dafür den Open-Source-Agenten actions/runner von GitHub. Der Runner baut eine ausgehende HTTPS-Verbindung zu GitHub auf, um Arbeit zu empfangen. Mit Stand vom 4. November 2026 ist die Compute-Nutzung selbst gehosteter Runner laut der Abrechnungsdokumentation von GitHub kostenlos; Sie zahlen für die Maschine und deren Wartung. Runner-Referenz von GitHub, GitHub Actions Abrechnung.

Wir entwickeln Lizard und verkaufen Runner für GitHub Actions; die Preise wurden am 4. November 2026 geprüft.

Der kürzeste Weg führt über eine Linux-VM, ein Registrierungstoken aus den Einstellungen Ihres Repositorys und einen Workflow mit passenden Runner-Labels. Beginnen Sie mit einem privaten Test-Repository. Für eine Runner-Flotte wählen Sie kurzlebige VMs, Kubernetes mit ARC oder das AWS-Terraform-Modul. Bei bereits vorhandenen Runnern können Sie direkt zu Sicherheit, Fehlersuche oder Maschinenkosten springen.

Selbst gehosteter Runner vs. von GitHub gehosteter Runner

GitHub stellt für jeden gehosteten Job eine frische Umgebung bereit und wartet sie. Bei einem selbst gehosteten Runner stellen Sie die Maschine bereit, patchen sie und sichern sie ab.

Quellen: die Übersicht zu selbst gehosteten Runnern, die Übersicht zu gehosteten Runnern und die Abrechnungsdokumentation von GitHub.

Bleiben Sie bei von GitHub gehosteten Runnern, wenn Ihr Open-Source-Projekt bereits kostenlos läuft oder Ihr Team keine Build-Maschinen warten möchte. Der eigene Betrieb ist sinnvoll, wenn Sie bestimmte Hardware oder Zugriff auf ein privates Netzwerk benötigen oder genügend kontinuierliche Arbeit haben, um den Betrieb der Maschinen zu rechtfertigen.

Welches Setup passt?

Wie richten Sie einen selbst gehosteten Runner für GitHub Actions auf Linux ein?

So fügen Sie einen selbst gehosteten Runner für GitHub Actions hinzu:

1. Öffnen Sie in Ihrem Repository Settings → Actions → Runners → New self-hosted runner.
2. Laden Sie actions/runner herunter und prüfen Sie dessen SHA-256-Prüfsumme.
3. Registrieren Sie ihn mit ./config.sh, der Repository-URL und dem Registrierungstoken von der Seite.
4. Starten Sie ./run.sh und bestätigen Sie, dass der Runner auf Jobs wartet.
5. Senden Sie einen Job mit runs-on: [self-hosted, linux, x64, linux-build], passend zum benutzerdefinierten Label unten.

Verwenden Sie eine x64-VM mit Ubuntu 24.04 oder Debian 12 und systemd. Melden Sie sich mit einem normalen Nutzerkonto an, das sudo verwenden kann, nicht als root. Sie benötigen ein privates GitHub-Repository, das Sie administrieren, ausgehenden Internetzugriff sowie genügend Speicherplatz und Arbeitsspeicher für Ihren Build. Die Runner-Anforderungen von GitHub unterstützen beide Betriebssysteme und verlangen ausgehendes HTTPS auf Port 443. Der Runner benötigt keinen eingehenden Webhook-Port.

Am 4. November 2026 haben wir diese Schritte auf einer frischen x64-VM mit Debian 12, systemd und actions/runner v2.338.2 getestet: Download und Prüfsumme, Registrierung bei einem privaten Test-Repository, den Smoke-Test-Workflow, Service-Installation, Entfernung sowie einen JIT-Runner auf Repository-Ebene. Die Ausgaben unten sind Ausschnitte aus diesem Test; unser Testnutzer war builder.

Runner herunterladen und überprüfen

Öffnen Sie im Repository Settings → Actions → Runners → New self-hosted runner und wählen Sie dann Linux und x64. Für einen Organisations-Runner verwenden Sie die Organisationseinstellungen und das Konto eines Organisationsinhabers. Enterprise-Administratoren können Runner auch auf Enterprise-Ebene hinzufügen. Die Einrichtungsanleitung von GitHub erklärt die einzelnen Geltungsbereiche.

Führen Sie dies in Bash unter Ihrem normalen Nutzerkonto statt als root aus. Es ruft die aktuelle Version und deren SHA-256-Prüfsumme über die Release-API von GitHub ab und prüft anschließend das Archiv, bevor es entpackt wird:

sudo apt-get update
sudo apt-get install -y ca-certificates curl jq
mkdir actions-runner
cd actions-runner
curl -fsSL https://api.github.com/repos/actions/runner/releases/latest -o release.json
RUNNER_VERSION=$(jq -er '.tag_name | ltrimstr("v")' release.json)
RUNNER_TARBALL="actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz"
RUNNER_URL=$(jq -er --arg name "$RUNNER_TARBALL" \
  '.assets[] | select(.name == $name) | .browser_download_url' release.json)
RUNNER_SHA=$(jq -er --arg name "$RUNNER_TARBALL" \
  '.assets[] | select(.name == $name) | .digest | select(startswith("sha256:")) | ltrimstr("sha256:")' release.json)
curl -fsSL "$RUNNER_URL" -o "$RUNNER_TARBALL"
printf '%s  %s\n' "$RUNNER_SHA" "$RUNNER_TARBALL" | sha256sum -c - && \
  tar xzf "$RUNNER_TARBALL" && \
  sudo ./bin/installdependencies.sh && \
  ./config.sh --help

Erwartetes Ergebnis: actions-runner-linux-x64-2.338.2.tar.gz: OK. Das Entpacken erfolgt nur bei erfolgreicher Prüfsummenprüfung; brechen Sie ab, wenn sie fehlschlägt oder GitHub keine Prüfsumme liefert. Releases werden schrittweise ausgerollt, verwenden Sie daher bei Bedarf die Version und Prüfsumme von der Einrichtungsseite Ihres Repositorys. GitHub-Runner-Releases.

Auf Debian 12 gab installdependencies.sh beim Durchprobieren von ICU-Versionen E: Unable to locate package libicu80 und ähnliche Zeilen aus, bevor es libicu72 fand. Diese Versuche mit Ersatzversionen waren in unserem Test zu erwarten; prüfen Sie, ob das Skript erfolgreich beendet wird.

Runner registrieren und auf Jobs warten lassen

Kopieren Sie das Registrierungstoken von der Einrichtungsseite. Laut GitHub läuft dieses Token nach einer Stunde ab. Es ist ein Token zur Runner-Registrierung, kein persönliches Zugriffstoken. Ersetzen Sie unten YOUR_OWNER/YOUR_REPO durch den Repository-Pfad; für den Organisationsbereich verwenden Sie https://github.com/YOUR_ORG.

read -rsp 'Registration token: ' RUNNER_TOKEN
printf '\n'
./config.sh --unattended \
  --url https://github.com/YOUR_OWNER/YOUR_REPO \
  --token "$RUNNER_TOKEN" \
  --name linux-build-01 \
  --labels linux-build
unset RUNNER_TOKEN
./run.sh

Erwartetes Ergebnis: √ Connected to GitHub, √ Runner successfully added, √ Settings Saved., dann Listening for Jobs nach ./run.sh. Achten Sie unter Settings → Actions → Runners auf Idle, wenn der Runner verbunden und bereit ist. Lassen Sie das Terminal für den ersten Job laufen. Registrierung, Runner-Status.

Einen Job an den Runner senden

Committen Sie diese Datei als .github/workflows/runner-check.yml auf dem Standardbranch Ihres Repositorys:

name: Check self-hosted runner
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  check:
    runs-on: [self-hosted, linux, x64, linux-build]
    steps:
      - name: Show the execution environment
        run: |
          echo "Runner accepted the job"
          uname -s -m
          whoami

Öffnen Sie Actions → Check self-hosted runner → Run workflow. Erwartetes Ergebnis aus unserem Test: Runner accepted the job / Linux x86_64 / builder. Ihr Nutzername kann abweichen. Dieser Smoke-Test benötigt weder Checkout noch Toolchain; fügen Sie diese für Ihren Build hinzu. Bleibt der Job in der Warteschlange, lesen Sie, warum der Job wartet.

GitHub gleicht alle Labels in der Liste unter runs-on ab. Der Runner erhält self-hosted, linux und x64 bei der Registrierung; linux-build ist unser benutzerdefiniertes Beispiellabel. Ein Label beschreibt einen Runner, installiert aber keine Software und gewährt keinen Repository-Zugriff. Workflow-Routing bei GitHub.

Als Service weiterlaufen lassen

Drücken Sie nach Abschluss des Tests Strg+C und vergewissern Sie sich vor dem Start des Services, dass der im Vordergrund laufende Listener ./run.sh beendet wurde. Andernfalls kann das Journal A session for this runner already exists. und Conflict anzeigen, während der alte Listener Jobs annimmt. Das ist uns im Test passiert. Führen Sie im Runner-Verzeichnis unter demselben normalen Nutzerkonto statt als root Folgendes aus:

sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

Erwartetes Ergebnis: Active: active (running) von svc.sh status. GitHub erstellt svc.sh nach der Registrierung; unter systemd halten diese Befehle den Runner über Abmeldung und Neustart hinweg am Laufen. Service-Einrichtung bei GitHub.

Einen Runner entfernen

Wählen Sie unter Settings → Actions → Runners den Runner aus und klicken Sie auf Remove, um ein Entfernungstoken zu erhalten. Stoppen und deinstallieren Sie den Service aus dessen Verzeichnis heraus und entfernen Sie dann die Registrierung:

sudo ./svc.sh stop
sudo ./svc.sh uninstall
read -rsp 'Removal token: ' REMOVAL_TOKEN
printf '\n'
./config.sh remove --token "$REMOVAL_TOKEN"
unset REMOVAL_TOKEN

Erwartetes Ergebnis: √ Runner removed successfully, √ Removed .credentials, √ Removed .runner. Die Anleitung von GitHub zum Entfernen von Runnern beschreibt die Benutzeroberfläche; eine Automatisierung kann ein Entfernungstoken für das Repository anfordern.

Wie unterscheiden sich Runner-Gruppen von Labels?

Eine Runner-Gruppe für GitHub Actions steuert, welche Repositorys eine Gruppe von Runnern nutzen können. Labels helfen dabei, innerhalb dieser zugelassenen Gruppe einen Runner auszuwählen. Öffnen Sie für Organisations-Runner Settings → Actions → Runner groups, wählen Sie eine Gruppe aus und beschränken Sie Repository access auf die Repositorys, die Zugriff benötigen. Runner-Gruppensteuerung bei GitHub.

Erstellen Sie für einen Organisations-Runner eine Gruppe namens trusted-builds und registrieren Sie ihn dann mit --url https://github.com/YOUR_ORG --runnergroup trusted-builds. Die Gruppe muss bereits existieren; dieses Flag gilt nicht für die oben beschriebene Einrichtung auf Repository-Ebene. Ein Job kann sowohl Gruppe als auch Label voraussetzen:

runs-on:
  group: trusted-builds
  labels: linux-build

Halten Sie Release-Jobs von Runnern fern, die von weniger vertrauenswürdigen Repositorys verwendet werden. Gruppen schränken ein, wer Arbeit einplanen kann; sie isolieren keine Prozesse und machen gemeinsam genutzte Datenträger nicht sicher. Die Routing-Dokumentation von GitHub verlangt sowohl Gruppenzugriff als auch passende Labels.

Wie funktionieren kurzlebige und Just-in-Time-Runner?

Ein kurzlebiger Runner nimmt einen Job an, bevor GitHub seine Registrierung entfernt; aktivieren Sie dieses Verhalten mit --ephemeral. Ihre Infrastruktur muss die VM weiterhin löschen oder den Inhalt ihrer Datenträger löschen. GitHub empfiehlt kurzlebige Runner für Autoscaling und weist darauf hin, vor dem Produktiveinsatz für eine externe Aufbewahrung ihrer Logs zu sorgen. Autoscaling-Referenz von GitHub.

Wenn Sie einen früheren Runner mit demselben Label linux-build behalten haben, stoppen Sie dessen Service mit sudo ./svc.sh stop oder verwenden Sie sowohl beim neuen Runner als auch im Workflow ein anderes Label. Andernfalls kann GitHub den Testjob an den früheren Runner senden. Verwenden Sie auf einer frischen VM mit einem noch nicht konfigurierten Runner-Verzeichnis ein neues Registrierungstoken:

read -rsp 'Registration token: ' RUNNER_TOKEN
printf '\n'
./config.sh --unattended \
  --url https://github.com/YOUR_OWNER/YOUR_REPO \
  --token "$RUNNER_TOKEN" \
  --name "ephemeral-$(hostname)" \
  --labels linux-build \
  --ephemeral
unset RUNNER_TOKEN
./run.sh

Löschen Sie die Maschine, wenn der Listener beendet wird, auch nach Fehlern. Berücksichtigen Sie außerdem Abbrüche und Maschinen, die nie einen Job erhalten. Dieselbe bereits benutzte VM erneut zu registrieren schafft keine saubere Umgebung.

Eine Just-in-Time-Konfiguration über die API erzeugen

Ein JIT-Runner erhält seine Konfiguration beim Start und kann höchstens einen Job ausführen. Eine Bereitstellungskomponente kann diese Konfiguration abrufen, ohne langlebige Zugangsdaten für die GitHub-API auf dem Worker abzulegen. GitHub warnt weiterhin davor, dass die Wiederverwendung der zugrunde liegenden Hardware eine saubere Umgebung erfordert. JIT-Sicherheitshinweise von GitHub.

Verwenden Sie für dieses Beispiel auf Organisationsebene ein für die Organisation autorisiertes API-Token mit der Berechtigung Self-hosted runners: write. Ein Organisationsadministrator kann für einen Test ein Token mit fein abgestuften Berechtigungen verwenden; für die Automatisierung verwenden Sie ein Installationstoken einer GitHub App. Ermitteln Sie die numerische Gruppen-ID über die Runner-Gruppen-API von GitHub und schränken Sie zuerst den Repository-Zugriff dieser Gruppe ein.

Ersetzen Sie in Bash die Platzhalter für Organisation und Gruppe. Führen Sie dies aus dem Runner-Verzeichnis auf einer frischen Maschine aus (wiederholen Sie zuerst den Downloadblock), nur für einen vertrauenswürdigen Test; im Produktivbetrieb führen Sie die API-Anfrage in der Bereitstellungskomponente aus und übermitteln ausschließlich die zurückgegebene Konfiguration an den Worker.

ORG='YOUR_ORG'
RUNNER_GROUP_ID='REPLACE_WITH_NUMERIC_GROUP_ID'
read -rsp 'GitHub API token: ' GH_API_TOKEN
printf '\n'
JIT_CONFIG=$(
  jq -n --arg name "jit-$(date +%s)" --argjson group "$RUNNER_GROUP_ID" \
    '{name: $name, runner_group_id: $group,
      labels: ["self-hosted", "linux", "x64", "linux-build"],
      work_folder: "_work"}' |
  curl -fsSL -X POST \
    -H 'Accept: application/vnd.github+json' \
    -H "Authorization: Bearer $GH_API_TOKEN" \
    -H 'X-GitHub-Api-Version: 2026-03-10' \
    --data-binary @- \
    "https://api.github.com/orgs/$ORG/actions/runners/generate-jitconfig" |
  jq -er '.encoded_jit_config'
)
unset GH_API_TOKEN
[ -n "$JIT_CONFIG" ] && ./run.sh --jitconfig "$JIT_CONFIG"
unset JIT_CONFIG

GitHub dokumentiert diese JIT-Anfrage auf Organisationsebene und einen JIT-Endpunkt auf Repository-Ebene für Tests mit einem einzelnen Repository; unser Test verwendete Letzteren mit runner_group_id: 1. Das Flag --jitconfig funktioniert, obwohl ./run.sh --help es nicht aufführt. Behandeln Sie die kodierte Konfiguration als Secret; das Routing hängt weiterhin von Geltungsbereich, Gruppen und Labels ab.

Erwartetes Ergebnis nach dem JIT-Job: Job check completed with result: Succeeded, √ Removed .credentials, √ Removed .runner, dann Runner listener exit with 0 return code, stop the service, no retry needed. und Exiting runner....

Wie betreiben Sie einen selbst gehosteten GitHub-Runner in Docker?

Das von GitHub gepflegte Image ghcr.io/actions/actions-runner führt den Agenten in einem Container aus. Dieses Beispiel verwendet den Tag 2.338.2, die neueste Runner-Version am 4. November 2026; wir haben dessen Linux-x64-Manifest geprüft, damit aber keinen Docker-Job ausgeführt.

Installieren Sie zuerst Docker Engine anhand der Ubuntu-Anleitung oder Debian-Anleitung von Docker. Der Befehl verwendet sudo; die alternative Einrichtung über die Gruppe docker gewährt Zugriff mit Root-Rechten.

Rufen Sie über die API generate-jitconfig von GitHub mit der JIT-Anfrage eine frische Konfiguration für einen Job ab, überspringen Sie aber deren Zeilen zum lokalen Runner-Start und zu unset JIT_CONFIG. Führen Sie mit der zurückgegebenen Konfiguration in JIT_CONFIG Folgendes aus:

sudo docker run --rm --init --platform linux/amd64 \
  --entrypoint /home/runner/run.sh \
  ghcr.io/actions/actions-runner:2.338.2 \
  --jitconfig "$JIT_CONFIG"
unset JIT_CONFIG

Senden Sie den Smoke-Test-Workflow an das Label des Containers. Dieser läuft als Nutzer runner des Images, bindet keinen persistenten Arbeitsbereich ein und wird beim Beenden entfernt. Der Image-Quelltext von GitHub listet die enthaltenen Tools auf; ergänzen Sie Build-Abhängigkeiten in einem abgeleiteten Image.

Den Agenten in Docker auszuführen ist etwas anderes, als über die Einstellung container: eines Workflows Job-Schritte in Docker auszuführen. GitHub verlangt für Docker-Container-Actions und Service-Container Linux und eine funktionierende Docker-Installation. Der obige Befehl konfiguriert keinen Docker-Daemon für verschachtelte Container-Jobs. Container-Jobs bei GitHub.

Das Einbinden des Docker-Sockets des Hosts erlaubt Job-Code, diesen Daemon zu steuern, wodurch das Dateisystem des Hosts zugänglich werden kann. Docker-in-Docker erfordert häufig einen privilegierten Container und braucht ein eigenes Konzept für Datenträger, Netzwerk und Bereinigung. Keiner der beiden Ansätze macht einen gewöhnlichen, gemeinsam genutzten Docker-Host sicher für bösartige pull requests. Isolieren Sie nicht vertrauenswürdige Jobs durch eine VM, die nach dem Job verworfen wird, und lesen Sie die Sicherheitshinweise zum Daemon von Docker.

Wie skalieren Sie auf Kubernetes mit Actions Runner Controller automatisch?

Actions Runner Controller (ARC) ist ein Open-Source-Controller auf Kubernetes für selbst gehostete Runner für GitHub Actions, gepflegt von GitHub und Mitwirkenden aus der Community. Er erstellt Runner-Pods für Jobs in der Warteschlange und skaliert die Flotte innerhalb Ihrer Einstellungen für minRunners und maxRunners, bei entsprechender Konfiguration bis auf null. Verwenden Sie ihn, wenn Ihr Team bereits Kubernetes betreibt; der ARC-Schnellstart von GitHub setzt einen Cluster und Helm 3 voraus. ARC-Architektur.

Installieren Sie den Controller in einem eigenen Namespace:

helm install arc \
  --namespace arc-systems \
  --create-namespace \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
kubectl create namespace arc-runners

Erstellen und installieren Sie für dieses Beispiel auf Organisationsebene eine GitHub App mit Self-hosted runners: read and write für die Organisation und Metadata: read-only für Repositorys. Speichern Sie ihren privaten Schlüssel lokal als github-app.pem. Die Registrierung auf Repository-Ebene erfordert außerdem Administration: read and write. Folgen Sie der ARC-Authentifizierungsanleitung von GitHub.

Ersetzen Sie die App- und Installations-IDs und erstellen Sie dann das Secret im Runner-Namespace:

kubectl create secret generic arc-github-app \
  --namespace arc-runners \
  --from-literal=github_app_id=YOUR_APP_ID \
  --from-literal=github_app_installation_id=YOUR_INSTALLATION_ID \
  --from-file=github_app_private_key=./github-app.pem

Speichern Sie dies als runner-values.yaml. Das Beispiel wählt null Runner im Leerlauf und höchstens vier Runner; das sind Ihre Budgeteinstellungen, keine Produktlimits von ARC.

githubConfigUrl: https://github.com/YOUR_ORG
githubConfigSecret: arc-github-app
runnerScaleSetName: arc-linux
minRunners: 0
maxRunners: 4

Installieren Sie die Runner-Skalierungsgruppe und prüfen Sie den Controller:

helm install arc-linux \
  --namespace arc-runners \
  --values runner-values.yaml \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
helm list -A
kubectl get pods -n arc-systems

Ersetzen Sie im vorherigen Smoke-Test-Workflow die Labelliste durch:

runs-on: arc-linux

Lösen Sie den Workflow aus und beobachten Sie den Runner-Namespace:

kubectl get pods -n arc-runners -w

Das von GitHub beschriebene erwartete Ergebnis ist ein laufender Controller und ein für den Job erstellter Runner-Pod. Die Runner-Pods auf null zu skalieren beseitigt nicht die laufenden Grundkosten Ihres Clusters. Diese Chart-Namen und Werte wurden mit der Deployment-Dokumentation und den Chart-Werten von GitHub abgeglichen; für diesen Artikel haben wir keinen Cluster bereitgestellt.

Fixieren Sie vor dem Produktiveinsatz getestete Chart- und Image-Versionen, sammeln Sie Controller- und Runner-Logs und setzen Sie Ressourcenanforderungen für Pods, die zu Ihren Builds passen. Beschränken Sie den Zugriff auf das Secret der GitHub App. Wählen Sie für Container-Jobs den dokumentierten Docker-in-Docker- oder Kubernetes-Containermodus von ARC und prüfen Sie dessen Berechtigungen. Die obigen Minimalwerte konfigurieren keinen der beiden Modi.

Wie skalieren Sie selbst gehostete Runner auf AWS automatisch?

terraform-aws-github-runner ist ein Open-Source-Modul für Terraform, das selbst gehostete Runner auf EC2 in Ihrem AWS-Konto automatisch skaliert, ohne Kubernetes. Die Webhook-basierte Einrichtung empfängt über eine GitHub App Ereignisse zu Jobs in der Warteschlange und verwendet Lambda und SQS, um den Bedarf zu steuern. Sie unterstützt kurzlebige Runner und Spot-Instanzen. Projektarchitektur.

Verwenden Sie das zu Ihrem Setup passende Projektbeispiel und fixieren Sie die Modulversion. Stellen Sie Ihre VPC, Subnetze, GitHub App und Ihr Runner-Image bereit und prüfen Sie vor der Anwendung die IAM-Berechtigungen und den Terraform-Plan. Planen Sie für unterbrochene Spot-Jobs, fehlgeschlagene Bereitstellung und verwaiste Instanzen. Rechnen Sie EC2, Datenträger, Logs, Netzwerkdienste und die AWS-Ressourcen des Controllers in die Rechnung ein.

Wählen Sie dieses Setup, wenn Ihre Richtlinien Runner in Ihrem AWS-Konto verlangen. Ihr Team patcht weiterhin Images und kümmert sich um Fehler. Wir haben dieses Terraform-Setup für den Artikel nicht bereitgestellt.

Können Sie selbst gehostete Runner für öffentliche Repositorys sicher nutzen?

Nicht ohne Weiteres. GitHub empfiehlt selbst gehostete Runner nur für private Repositorys, weil ein pull request aus einem Fork vom Angreifer kontrollierten Code auf der Maschine ausführen kann. Auch private Repositorys erfordern Vorsicht: Wer forken und einen pull request öffnen darf, kann möglicherweise Code in Ihrer Runner-Umgebung ausführen. Sicherheitshinweise von GitHub.

Für öffentliche Beiträge sind von GitHub gehostete Runner der sicherere Ausgangspunkt. Verbinden Sie die persistente VM aus diesem Tutorial nicht mit einem öffentlichen Repository. Wenn Sie nicht vertrauenswürdigen Code selbst hosten müssen, verwenden Sie für jeden Job eine isolierte Umgebung, die danach verworfen wird, mit eingeschränkten Zugangsdaten und eingeschränktem Netzwerkzugriff. Eine kurzlebige Registrierung allein bietet diese Isolation nicht.

• Halten Sie SSH-Schlüssel, Cloud-Administrator-Zugangsdaten und Produktionsdaten von Runner-Datenträgern fern. Verwenden Sie nach Möglichkeit kurzlebige Zugangsdaten mit eng begrenztem Geltungsbereich.
• Trennen Sie Repositorys mit unterschiedlichen Vertrauensstufen durch Runner-Gruppen und separate Ausführungsumgebungen. Ein benutzerdefiniertes Label ist keine Zugriffskontrolle.
• Checken Sie einen nicht vertrauenswürdigen pull request nicht in einem privilegierten pull_request_target-Workflow aus und führen Sie ihn dort nicht aus. Prüfen Sie Ereignisberechtigungen und Freigaberichtlinien für Läufe aus Forks.
• Beschränken Sie den Zugriff auf interne Dienste und Cloud-Metadatenendpunkte. Erlauben Sie die GitHub-Endpunkte, die Ihre Jobs benötigen, sowie die Registrys für deren Abhängigkeiten; auch ausschließlich ausgehende Verbindungen ermöglichen Datendiebstahl.
• Behandeln Sie Caches als gemeinsam genutzten Zustand. Verhindern Sie, dass nicht vertrauenswürdige Jobs Daten schreiben, die später von einem privilegierten Build ausgeführt werden.

Diese Maßnahmen folgen den Hinweisen von GitHub zur sicheren Nutzung. Die Kommunikationsreferenz listet die Domains auf, die für Runner-Updates, Actions, Logs, Artefakte und Caches benötigt werden.

Runner und Image aktuell halten

Die Runner-Referenz von GitHub verlangt bei Runnern mit deaktivierten automatischen Updates eine Aktualisierung innerhalb von 30 Tagen nach einem neuen Release, einschließlich Patch-Releases. GitHub weist veralteten Runnern keine Arbeit mehr zu; ein erforderliches kritisches Sicherheitsupdate kann Jobs schon früher blockieren. Update-Richtlinie von GitHub.

Der Runner aktualisiert sich normalerweise selbst. Verwenden Sie --disableupdate nur, wenn Ihr Team Runner-Images innerhalb dieser Frist neu baut. Agenten-Updates patchen weder Ubuntu noch Docker noch Ihre Build-Tools. Ersetzen Sie Maschinen für die Wartung oder lassen Sie laufende Jobs auslaufen, ohne neue anzunehmen und ohne aktive Jobs zu unterbrechen.

Warum ist der Runner offline oder wartet der Job?

Ein Job wartet, wenn kein verbundener Runner im Leerlauf zu seinen Labels und seinem erlaubten Geltungsbereich oder seiner Gruppe passt. Ein Offline-Runner wartet nicht mehr auf Jobs oder kann GitHub nicht erreichen. Laut der Routing-Referenz von GitHub schlagen Jobs in der Warteschlange nach mehr als 24 Stunden fehl.

Die Referenz zur Fehlersuche von GitHub behandelt Runner-Status, Logs, Verbindungen und Docker-Berechtigungen.

Prüfen Sie auf der Maschine mit systemd beispielsweise die letzten 100 Journal-Zeilen, danach die Diagnosedateien und die Datenträgerbelegung:

sudo ./svc.sh status
sudo journalctl -u "$(cat .service)" -n 100 --no-pager
ls -lt _diag/
df -h

In _diag beschreiben Dateien mit Runner_ den Listener und Dateien mit Worker_ einzelne Jobs. Sichern Sie diese, bevor Sie kurzlebige Runner löschen. Wenn der Job nie gestartet ist, lesen Sie das neueste Runner_-Log; wenn er gestartet und fehlgeschlagen ist, lesen Sie sein Worker_-Log und die Job-Ausgabe.

Was kostet die Maschine für einen selbst gehosteten Runner?

Planen Sie Kosten für die Maschine und ihre Wartung ein: Image-Patches, Datenträgerbereinigung, Monitoring und fehlgeschlagene Jobs.

Mit Stand vom 4. November 2026 führt die Abrechnungsdokumentation von GitHub Compute-Nutzung auf selbst gehosteten Runnern nach der Verschiebung der vorgeschlagenen Gebühr weiterhin als kostenlos auf; Gebühren und enthaltene Nutzung finden Sie in der vollständigen Preisliste für GitHub Actions.

Beispiel: eine durchgehend laufende Linux-VM

Am 4. November 2026 führte die Preistabelle für Basic Regular Droplet von DigitalOcean 2 geteilte vCPU, 4 GiB RAM, 80 GiB SSD und 4.000 GiB Datentransfer für 24 $ pro Monat auf. Laut der Abrechnungsdokumentation werden Droplets mit gebündelten Ressourcen auch im ausgeschalteten Zustand weiter berechnet; löschen Sie den Droplet, um die Berechnung zu beenden.

Angenommen, die VM läuft den ganzen Monat in NYC3, wo Basic Droplets verfügbar sind, verarbeitet die Builds Ihres privaten Repositorys nacheinander und es gibt keine Gutschriften oder Nutzung über das Paket hinaus. Dieses Budgetbeispiel schließt Steuern, Backups, Snapshots, zusätzlichen Speicher oder Traffic, GitHub-Gebühren und Arbeitszeit für den Betrieb aus; es trifft keine Aussage zur Leistung.

Der Rechnungsposten für die VM bleibt unter diesen Annahmen bei 24 $, unabhängig davon, ob sie gelegentliche Jobs verarbeitet oder durchgehend ausgelastet ist. Weisen Sie jemandem die Wartung zu, bevor Sie sich bei Releases auf die VM verlassen.

Vergleichen Sie vollständige Monatsrechnungen anhand des aktuellen Job-Verlaufs, einschließlich ungenutzter Kapazität und Wiederholungsversuchen, und rechnen Sie Ihr Kontingent für von GitHub gehostete Runner an, bevor Sie kostenpflichtige Nutzung vergleichen.

Wann ist ein verwalteter Runner die bessere Wahl?

Runner für GitHub Actions bei Lizard führen actions/runner von GitHub anhand einer JIT-Konfiguration für jeden Job in einer frischen Firecracker-VM aus; anschließend wird die Runner-Registrierung entfernt. Lizard hält nur für private Repositorys eine Cache-Disk vor, und Jobs aus Forks laufen niemals damit. Der Cache kann von pull requests und anderen Branches gelesen werden, aber nur Pushes, geplante und manuelle Läufe auf dem Standardbranch speichern darin.

Lizard Pro kostet 19 $ im Monat, inklusive Steuern und 19 $ enthaltener Nutzung; das ist der monatliche Mindestbetrag, darüber hinausgehende Nutzung wird nach dem Modell pay as you go abgerechnet. Die VM-Zeit des Runners wird sekundengenau abgerechnet, einschließlich Einrichtungs- und Leerlaufzeit.

Runner von Lizard unterstützen ausschließlich Linux x64 auf Ubuntu 24.04 und GitHub-Organisationen, keine persönlichen Konten. Ein Organisationsadministrator installiert die Lizard GitHub App. Die 7-tägige Testphase erfordert eine Karte, enthält 5 $ Nutzung und erlaubt nur Runner der Größe Small mit bis zu 4 vCPU gleichzeitig; Arbeitslasten werden pausiert, sobald die Testnutzung aufgebraucht ist, sofern Sie nicht Pro starten.

Verwenden Sie das Label für Small für einen Testjob:

runs-on: lizard-small-ubuntu-2404

Jobs für Windows, macOS und ARM bleiben bei GitHub; wählen Sie für GPU-Jobs einen geeigneten Anbieter. Vergleichen Sie Anbieter mit Benchmarks, wenn eine möglichst kurze Build-Zeit wichtig ist, verwenden Sie bei Bedarf ein Setup in Ihrer eigenen Cloud und behalten Sie kostenlose, von GitHub gehostete Runner für öffentliche Projekte bei, wenn sie Ihre Anforderungen erfüllen. Siehe den Vergleich verwalteter Runner und anderer CI-Plattformen.

Lizard war bei unserem Frontend-Build günstiger und langsamer; sehen Sie sich den gemessenen Build und die Runner-Einrichtung bei Lizard an, testen Sie dann einen vertrauenswürdigen Linux-Job und vergleichen Sie dessen Laufzeit, Gesamtrechnung und Wartungsaufwand.

Häufige Fragen

Wie setzen Sie Umgebungsvariablen auf einem selbst gehosteten Runner für GitHub Actions? Tragen Sie beispielsweise BUILD_MODE=test in actions-runner/.env ein und starten Sie den Service anschließend mit sudo ./svc.sh stop und sudo ./svc.sh start neu. Verwenden Sie wörtliche NAME=value-Zeilen ohne export, Shell-Expansion oder Anführungszeichen um Werte. Die Proxy-Anleitung von GitHub dokumentiert die Verwendung von .env; der Parser des Runners liest sie beim Start, während env.sh PATH separat in .path speichert. Jobs können diese Werte lesen, verwenden Sie daher env: im Workflow für Job-Einstellungen und GitHub-Secrets für Zugangsdaten. Halten Sie .env aus der Versionsverwaltung heraus.

Sind selbst gehostete GitHub-Runner kostenlos? Mit Stand vom 4. November 2026 erhebt GitHub laut seiner Abrechnungsdokumentation keine Compute-Gebühr für selbst gehostete Runner. Sie zahlen weiterhin für die Maschine und ihre Wartung.

Benötigt ein selbst gehosteter Runner einen offenen eingehenden Port? Nein. Die Kommunikationsanforderungen von GitHub verlangen ausgehendes HTTPS auf Port 443; der Runner benötigt keinen eingehenden Webhook-Port.

Wie lange ist ein Token zur Runner-Registrierung gültig? Laut der Runner-Einrichtungsanleitung von GitHub eine Stunde. Erzeugen Sie ein frisches Token, wenn die Registrierung wegen eines abgelaufenen Tokens fehlschlägt.