GitHub Actions Runner auf VPS selbst hosten

Was ein selbst gehosteter GitHub Actions Runner macht

Ein selbst gehosteter GitHub Actions Runner ist ein Programm, das Sie auf Ihrem eigenen VPS installieren. Es fragt GitHub nach Aufträgen und führt sie auf Ihrer Hardware aus. Sie registrieren ihn für ein Repository und installieren ihn als systemd-Dienst. Nach jedem Reboot wird er wieder gestartet. GitHub plant den Auftrag ein. Ihr Server führt ihn aus.

CI (Continuous Integration) auf einem eigenen System ist aus zwei Gründen sinnvoll. Build-Minuten werden nicht mehr abgerechnet. Außerdem kann ein Auftrag auf Ressourcen zugreifen, die nur auf Ihrem System vorhanden sind, etwa einen vorgewärmten Build-Cache oder ein privates Netzwerk. Der Preis dafür ist ein Sicherheitsrisiko. Der Runner führt alles aus, was in der Workflow-Datei angegeben ist, und verwendet dabei den Benutzer, den Sie ihm zugewiesen haben. Eine Workflow-Datei ermöglicht daher absichtlich die Ausführung von Code aus der Ferne. Bei einem privaten Repository ist das unproblematisch, weil nur vertrauenswürdige Personen eine solche Datei hinzufügen können. Bei einem öffentlichen Repository besteht ein echtes Risiko. Der Abschnitt zu Pull Requests aus Forks erklärt den Mechanismus.

Alle folgenden Schritte beziehen sich auf Ubuntu 24.04 und die Runner-Version 2.338.0, die am 12 October 2026 aktuelle Version.

Was Sie vor dem Start benötigen

Beginnen Sie mit einem VPS mit einem normalen Administratorkonto und sudo, also mit dem Zustand aus den ersten zehn Minuten auf einem neuen VPS. Sie müssen keinen eingehenden Port öffnen. Der Runner baut eine ausgehende HTTPS-Verbindung (Hypertext Transfer Protocol Secure) zu GitHub auf und hält sie offen, während er auf Aufgaben wartet. GitHub verbindet sich daher nie mit Ihrem Server. Ihre Firewall kann für die Außenwelt geschlossen bleiben, und Jobs treffen trotzdem ein.

Sie benötigen außerdem Administratorrechte für das Repository, weil das Registrierungstoken in den Repository-Einstellungen angezeigt wird.

Einen dedizierten Benutzer für den Runner erstellen

Führen Sie den Runner niemals als root oder als Ihren eigenen Administratorkonto aus. Jeder Job übernimmt die Berechtigungen des Runner-Benutzers. Daher ist ein Workflow erfolgreich, der sudo aufruft, wenn der Runner-Benutzer sudo verwenden darf. Erstellen Sie einen nicht privilegierten Benutzer, dem außer seinem eigenen Home-Verzeichnis nichts gehört. Benutzerkonten mit minimalen Berechtigungen auf einem VPS beschreibt das allgemeine Vorgehen. Hier folgt die konkrete Umsetzung.

sudo useradd -m -s /bin/bash gharunner
sudo passwd -l gharunner
sudo chmod 750 /home/gharunner
sudo install -d -m 700 -o gharunner -g gharunner /home/gharunner/actions-runner

passwd -l sperrt das Passwort. Dadurch kann sich niemand mit diesem Passwort als gharunner anmelden. Der Modus 700 für das Runner-Verzeichnis ist wichtig, weil der Runner seine Zugangsdaten dort im Klartext speichert und ein Checkout private Quelldateien enthalten kann.

Prüfen Sie beide Eigenschaften, bevor Sie fortfahren:

sudo passwd -S gharunner
sudo -l -U gharunner

passwd -S gibt eine Zeile aus, die mit gharunner L beginnt. L bedeutet, dass das Passwort gesperrt ist. sudo -l -U gharunner sollte mit is not allowed to run sudo antworten. Wenn stattdessen eine Liste zulässiger Befehle ausgegeben wird, gehört das Konto zu einer sudo-Gruppe. Die gerade eingerichtete Isolation ist dann nicht mehr gegeben.

Download des Runners und Überprüfung des Tarballs

Arbeiten Sie ab hier als Benutzer gharunner.

sudo -iu gharunner
cd ~/actions-runner
RUNNER_VERSION=2.338.0
curl -fL -o actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz \
  "https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz"

Führen Sie zuerst uname -m aus, falls Sie sich bei der Architektur unsicher sind. x86_64 verwendet die oben genannte linux-x64-Datei. aarch64 verwendet actions-runner-linux-arm64-${RUNNER_VERSION}.tar.gz.

Überprüfen Sie nun den Download. Der unten stehende SHA256-Hash (Secure Hash Algorithm, 256 Bit) gilt für den x64-Tarball der Version 2.338.0. GitHub zeigt den Wert für die aktuelle Version auf der Release-Seite sowie auf dem Bildschirm "New self-hosted runner" an. Er ändert sich mit jeder Version; kopieren Sie ihn daher von dort, wenn Sie eine andere Version installieren.

echo "af4b794c1bc41d73d40535e3fe092a39f9679cd8d965954c2aca25a05ca41d32  actions-runner-linux-x64-2.338.0.tar.gz" | sha256sum -c

Ein erfolgreicher Download gibt eine Zeile aus:

actions-runner-linux-x64-2.338.0.tar.gz: OK

Eine abgeschnittene oder veränderte Datei führt zu einer Fehlermeldung und einer Warnung:

actions-runner-linux-x64-2.338.0.tar.gz: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match

Überspringen Sie die Überprüfung nicht, um das Problem stattdessen durch tar finden zu lassen. Ein unvollständig geschriebenes Archiv schlägt mit gzip: stdin: unexpected end of file und tar: Unexpected EOF in archive fehl; dies zeigt zwar an, dass die Datei beschädigt ist, aber nicht, ob sie abgeschnitten oder ersetzt wurde.

tar xzf ./actions-runner-linux-x64-2.338.0.tar.gz
ls

Was das Tarball enthält und was nicht

Nach dem Entpacken enthält das Verzeichnis config.sh, run.sh, env.sh, safe_sleep.sh, bin/ und externals/. bin/ enthält die Runner-Binärdateien und bin/installdependencies.sh. externals/ enthält die gebündelte Node-Laufzeitumgebung, auf der JavaScript-Actions ausgeführt werden.

svc.sh ist zu diesem Zeitpunkt noch nicht vorhanden. In der Dokumentation von GitHub wird sie als das Skript beschrieben, „das nach dem erfolgreichen Hinzufügen des Runners erstellt wird“. Sie wird aus einer Vorlage erzeugt, in der Ihr Repository und der Name des Runners in den Dienstnamen übernommen werden. Daher schlägt sudo ./svc.sh install vor ./config.sh mit sudo: ./svc.sh: command not found fehl. Registrieren Sie den Runner zuerst, und installieren Sie anschließend den Dienst.

Installation der Runner-Abhängigkeiten

Der Runner ist eine .NET-Anwendung und benötigt daher einige gemeinsam genutzte Bibliotheken. Verlassen Sie die Shell des Benutzers gharunner und installieren Sie diese mit sudo, da das Skript in die System-Paketdatenbank schreibt.

exit
cd /home/gharunner/actions-runner
sudo ./bin/installdependencies.sh

Unter Ubuntu 24.04 werden dadurch libkrb5-3, zlib1g, liblttng-ust1t64, libssl3t64 und libicu74 installiert. Das Skript versucht für jede Bibliothek verschiedene Versionsnamen und behält diejenige bei, die Ihre Distribution bereitstellt. Deshalb funktioniert dasselbe Skript sowohl unter älteren Ubuntu-Versionen als auch unter Debian.

Wenn Sie diesen Schritt überspringen und eine dieser Bibliotheken fehlt, bricht ./config.sh ab, bevor es weitere Aktionen ausführt:

Dependencies is missing for Dotnet Core 6.0
Execute sudo ./bin/installdependencies.sh to install any missing Dotnet Core 6.0 dependencies.

Eine fehlende libicu führt zum gleichen Hinweis unter einer anderen ersten Zeile, Libicu's dependencies is missing for Dotnet Core 6.0. Beide stammen aus derselben Quelle: config.sh prüft die gebündelten Bibliotheken mit ldd, und libicu mit ldconfig, bevor der Start erfolgt. Eine nicht aufgelöste Verknüpfung stoppt das Skript somit, anstatt später einen schwer nachvollziehbaren Absturz zu verursachen.

Registrieren Sie den Runner bei Ihrem Repository

Rufen Sie ein Token aus dem Repository ab. Öffnen Sie Settings, dann Actions, dann Runners und anschließend New self-hosted runner. Die Seite zeigt ein Registrierungs-Token an. Es läuft eine Stunde nach der Erstellung ab; generieren Sie es daher erst, wenn Sie bereit sind, es einzufügen.

Führen Sie die Registrierung als Benutzer gharunner aus. config.sh verweigert die Ausführung unter sudo.

sudo -iu gharunner
cd ~/actions-runner
./config.sh --url https://github.com/YOUR-USER/YOUR-REPO \
  --token PASTE_REGISTRATION_TOKEN_HERE \
  --name vps-runner-1 \
  --labels vps \
  --work _work \
  --unattended \
  --replace

Die Funktion dieser Flags: --name legt fest, wie der Runner im Repository erscheint. Wählen Sie einen Namen, den Sie auch in sechs Monaten noch zuordnen können. --labels fügt eigene Labels hinzu; der Runner besitzt bereits die Labels self-hosted, Linux und X64, ohne dass diese explizit angegeben werden müssen. --work benennt das Verzeichnis innerhalb des Runner-Verzeichnisses, in dem Checkouts abgelegt werden. --unattended beantwortet die interaktiven Abfragen mit ihren Standardwerten; dies ist empfehlenswert, wenn der Befehl in einem Skript verwendet wird. --replace übernimmt eine bestehende Registrierung mit demselben Namen, anstatt mit einem Fehler abzubrechen; dies ist empfehlenswert, wenn Sie den Server neu aufsetzen.

Ein erfolgreicher Durchlauf endet mit diesen Zeilen:

√ Runner successfully added
√ Runner connection is good
√ Settings Saved.

Die Registrierung ist nun im Runner-Verzeichnis als .runner, .credentials und .credentials_rsaparams hinterlegt. Die letzten beiden Dateien identifizieren diesen Runner gegenüber GitHub. Jeder, der diese Dateien lesen kann, kann sich als dieser Runner ausgeben. Aus diesem Grund hat das Verzeichnis den Modus 700 und der Benutzer verfügt über keine sudo-Rechte.

Installieren Sie den Runner als systemd-Dienst

./run.sh in einem Terminal eignet sich für einen einzelnen Test, wird jedoch mit Ihrer SSH-Sitzung beendet. Installieren Sie den Dienst, damit der Runner beim Booten startet. systemd-Dienste und Timer auf einem VPS erläutert die Unit-Dateien selbst. Hier erstellt svc.sh eine solche Datei für Sie.

exit
cd /home/gharunner/actions-runner
sudo ./svc.sh install gharunner
sudo ./svc.sh start
sudo ./svc.sh status

svc.sh erfordert root, weil das Skript eine Unit in /etc/systemd/system schreibt und sie aktiviert. Das Argument nach install gibt den Benutzer an, unter dem der Dienst ausgeführt wird. Übergeben Sie gharunner ausdrücklich. Ohne dieses Argument verwendet das Skript $SUDO_USER. Das ist Ihr Administratorkonto. Danach wird jeder Job mit einem Benutzer ausgeführt, der sudo verwenden kann.

Die Unit wird nach dem Repository und dem Runner benannt, und zwar im Format actions.runner.YOUR-USER-YOUR-REPO.vps-runner-1.service. Sie müssen diesen Namen nicht selbst eingeben:

systemctl list-units 'actions.runner.*'
sudo journalctl -u 'actions.runner.*' -n 20 --no-pager

Ein funktionsfähiger Runner protokolliert √ Connected to GitHub und anschließend eine Zeile, die mit Listening for Jobs endet. Auf der Seite Runners des Repositorys wird er dann als Idle angezeigt. Ein Runner mit dem Status Offline wird entweder nicht ausgeführt oder kann GitHub über Port 443 nicht erreichen.

Einen Auftrag an den Runner senden

runs-on wählt einen Runner anhand seines Labels aus. Fordern Sie zusätzlich self-hosted und Ihr eigenes Label an, damit ein Auftrag nicht auf einem Runner ausgeführt wird, den Sie nicht vorgesehen haben.

name: build
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: [self-hosted, linux, vps]
    steps:
      - uses: actions/checkout@v5
      - run: uname -a

Wenn der Auftrag bei Waiting for a runner to pick up this job wartet, stimmen die Labels nicht überein. Jedes Label in runs-on muss auf dem Runner vorhanden sein. Bereits ein zusätzliches Wort lässt den Auftrag ohne Fehlermeldung in der Warteschlange bleiben. Vergleichen Sie die Liste mit den Labels, die in den Repository-Einstellungen neben dem Runner angezeigt werden.

Warum selbst gehostete Runner und öffentliche Repositorys nicht zusammenpassen

Diesen Teil überspringen viele. Die Empfehlung von GitHub ist eindeutig: Selbst gehostete Runner „sollten fast nie für öffentliche Repositorys verwendet werden“. Außerdem gibt es „keine Garantie, dass sie in kurzlebigen, sauberen virtuellen Maschinen ausgeführt werden. Nicht vertrauenswürdiger Code in einem Workflow kann sie dauerhaft kompromittieren“.

Der Mechanismus ist einfach. Ein Pull Request aus einem Fork enthält eine eigene Kopie der Workflow-Datei. Wenn Ihr öffentliches Repository Pull-Request-Workflows auf Ihrem Runner ausführt, kann jeder, der das Repository forken kann, einen Workflow vorschlagen, der seine Befehle auf Ihrem VPS ausführt. Dafür ist kein Schreibzugriff erforderlich, weil genau der vorgeschlagene Inhalt ausgeführt wird.

Genehmigungseinstellungen entschärfen dieses Problem, beheben es aber nicht. Die Standardrichtlinie für ein öffentliches Repository fordert einen Maintainer auf, den Fork-Workflow eines erstmaligen Beitragenden zu genehmigen. GitHub betrachtet eine Person nur so lange als erstmalig beitragend, bis ein Commit oder Pull Request dieser Person in das Repository übernommen wurde. Danach werden ihre späteren Pull Requests ohne weitere Aufforderung ausgeführt. GitHub weist selbst darauf hin, dass dafür bereits eine triviale, übernommene Korrektur ausreicht. Die Sicherheitsprüfung besteht also darin, dass ein Mensch einen Diff liest. Eine in einem Build-Skript drei Ebenen tiefer versteckte Payload wird dabei leicht übersehen.

Ein Pull Request aus einem Fork erhält keine Ihrer Secrets, und sein GITHUB_TOKEN ist schreibgeschützt. Das begrenzt den Schaden innerhalb von GitHub. Für Ihren Server ändert das nichts. Der Angreifer verfügt über eine Shell als gharunner. Er kann daher jede Datei lesen, auf die dieser Benutzer zugreifen kann, jedes Ziel erreichen, das der VPS in seinem privaten Netzwerk erreichen kann, und etwas in ~/.bashrc oder in einer systemd-Unit des Benutzers hinterlassen, die während des nächsten Jobs ausgeführt wird.

Die Registrierung mit --ephemeral sorgt dafür, dass der Runner einen Job akzeptiert und sich anschließend deregistriert. Dadurch kann ein Job nicht den Workspace des nächsten Jobs lesen. Das hilft nur, wenn die Maschine oder der Container für jeden Job neu erstellt wird. Eine in das Home-Verzeichnis des Runner-Benutzers geschriebene Hintertür bleibt bei einer erneuten Registrierung erhalten.

Die folgenden Regeln sind kurz. Verwenden Sie selbst gehostete Runner für private Repositorys. Wenn Sie einen Runner an ein öffentliches Repository anbinden müssen, führen Sie darauf keine Pull Requests aus Forks aus, betreiben Sie auf diesem Server nichts anderes und behandeln Sie die Maschine als austauschbar.

Docker-Jobs und die Gruppe, die tatsächlich root bedeutet

Container-Jobs, Service-Container und jeder Workflow-Schritt, der docker build aufruft, benötigen einen Docker-Daemon auf dem Runner-Host. Installieren Sie Docker auf die übliche Weise. Eine Anleitung dazu finden Sie unter Docker und Docker Compose auf einem VPS. Fügen Sie anschließend den Runner-Benutzer der Gruppe docker hinzu.

Machen Sie sich vorab mit dem damit verbundenen Risiko vertraut. Die Mitgliedschaft in der Gruppe docker entspricht root, weil ein Container / als Bind-Mount einbinden und darin als root ausgeführt werden kann. Ein Workflow, der mit dem Docker-Socket kommunizieren kann, kann daher jede Datei auf dem VPS lesen und schreiben, einschließlich /etc/shadow. In einem privaten Repository mit vertrauenswürdigen Mitwirkenden kann dieser Preis akzeptabel sein. In allen anderen Fällen wird der Zweck des unprivilegierten Benutzers dadurch aufgehoben. Rootless Docker hält Container-Builds innerhalb der Berechtigungen des Runner-Benutzers. Dafür sind die Speicherzugriffe langsamer, und privilegierte Container werden nicht unterstützt.

Updates und sauberes Entfernen des Runners

Ein selbst gehosteter Runner aktualisiert sich standardmäßig selbst. Er erkennt eine neue Version, ersetzt seine eigenen Dateien und startet den Dienst neu. Normalerweise müssen Sie daher nichts tun. Um die Selbstaktualisierung zu deaktivieren, übergeben Sie bei der Registrierung des Runners --disableupdate an ./config.sh. Bei einem bereits registrierten Runner müssen Sie ihn dafür mit diesem Flag erneut registrieren. Dadurch lässt sich der Runner nicht dauerhaft auf einer Version festhalten. In der GitHub-Dokumentation wird ausdrücklich darauf hingewiesen, dass ein mit --disableupdate konfigurierter Runner weiterhin innerhalb von 30 Tagen nach einer neuen Version manuell aktualisiert werden muss. Andernfalls stellt GitHub keine Jobs mehr für ihn in die Warteschlange.

Eine manuelle Aktualisierung behält die Registrierung bei, weil sich .runner und .credentials nicht im Tarball befinden. Stoppen Sie den Dienst, laden Sie den neuen Tarball herunter und prüfen Sie seine Prüfsumme wie in gharunner beschrieben. Extrahieren Sie ihn mit tar xzf in dasselbe Verzeichnis. Starten Sie anschließend den Dienst wieder:

cd /home/gharunner/actions-runner
sudo ./svc.sh stop
sudo ./svc.sh start

Um den Runner zu entfernen, deinstallieren Sie zuerst den Dienst und heben Sie anschließend die Registrierung auf. Das Removal-Token erhalten Sie auf derselben Runners-Seite über die Schaltfläche Remove des Runners.

cd /home/gharunner/actions-runner
sudo ./svc.sh stop
sudo ./svc.sh uninstall
sudo -iu gharunner
cd ~/actions-runner
./config.sh remove --token PASTE_REMOVAL_TOKEN_HERE

Wenn Sie das Verzeichnis löschen, ohne die Registrierung aufzuheben, bleibt der Runner im Repository als Offline aufgeführt. Er bleibt dort, bis ein Administrator auf Force remove this runner klickt oder GitHub ihn nach 14 Tagen ohne Verbindung automatisch entfernt.

Fehlerbilder mit den angezeigten Meldungen

Must not run with sudo. config.sh gibt diese Meldung aus und beendet sich, wenn es als root ausgeführt wird. Die Prüfung ist absichtlich vorhanden, weil root gehörende Dateien in _work alle späteren Jobs beeinträchtigen, die als Servicebenutzer ausgeführt werden. Führen Sie ./config.sh als gharunner aus. Die Variable RUNNER_ALLOW_RUNASROOT überschreibt die Prüfung. Dadurch wird das Problem lediglich auf einen späteren Zeitpunkt verschoben.

sudo: ./svc.sh: command not found. Sie befinden sich im richtigen Verzeichnis. svc.sh ist noch nicht vorhanden, weil config.sh noch keine Registrierung abgeschlossen hat. Registrieren Sie den Runner und installieren Sie anschließend den Dienst.

Http response code: NotFound from 'POST https://api.github.com/actions/runner-registration'. In der Regel ist das Token kein gültiges Registrierungstoken. Entweder ist es abgelaufen, weil Registrierungstoken nur eine Stunde gültig sind, oder anstelle des Registrierungstokens von der Seite „Runners“ wurde ein persönliches Zugriffstoken eingefügt. Erzeugen Sie ein neues Token und fügen Sie es erneut ein. Prüfen Sie außerdem, dass --url die vollständige Repository-URL enthält.

Dependencies is missing for Dotnet Core 6.0. Führen Sie sudo ./bin/installdependencies.sh als root aus dem Runner-Verzeichnis aus und registrieren Sie den Runner anschließend erneut.

Runner nach einem Reboot offline. Führen Sie systemctl is-enabled 'actions.runner.*' aus. Wenn nichts aufgelistet wird, wurde ./svc.sh install nie ausgeführt. Der Runner existierte dann nur innerhalb Ihrer Terminalsitzung. Wenn die Unit aktiviert ist und der Runner weiterhin offline ist, lesen Sie journalctl -u 'actions.runner.*' und prüfen Sie die ausgehenden HTTPS-Verbindungen.

Der Datenträger läuft voll. Checkouts, Build-Caches und Docker-Images sammeln sich unter _work und im Home-Verzeichnis des Runner-Benutzers an. Sie werden nicht automatisch bereinigt. Überwachen Sie du -sh /home/gharunner/actions-runner/_work und richten Sie eine regelmäßige Bereinigung ein, bevor der Datenträger selbst die Entscheidung für Sie trifft.

FAQ

Warum meldet sudo ./svc.sh install command not found?

Weil svc.sh nicht im Runner-Tarball enthalten ist. Das Skript wird im Runner-Verzeichnis erzeugt, sobald ./config.sh die Registrierung abgeschlossen hat. Dabei werden der Name Ihres Repositorys und der Runner-Name zum Servicenamen kombiniert. Führen Sie zuerst ./config.sh als Runner-Benutzer aus. Danach findet sudo ./svc.sh install gharunner das Skript und schreibt eine Unit namens actions.runner.OWNER-REPO.RUNNER-NAME.service nach /etc/systemd/system.

Muss ich für einen Self-Hosted Runner einen Firewall-Port öffnen?

Nein. Der Runner baut eine ausgehende HTTPS-Verbindung zu GitHub auf und hält sie offen, während er auf Jobs wartet. GitHub initiiert daher keine Verbindung zu Ihrem VPS. Erlauben Sie ausgehenden Datenverkehr auf Port 443 und lassen Sie eingehende Verbindungen gesperrt. Wenn der Runner bei laufendem Dienst als Offline angezeigt wird, prüfen Sie die Filterung ausgehender Verbindungen und DNS statt der eingehenden Regeln.

Kann ich einen Self-Hosted Runner in einem öffentlichen Repository verwenden?

Das ist möglich, wird von GitHub jedoch nicht empfohlen. Ein Pull Request aus einem Fork enthält seine eigene Workflow-Datei. Jeder, der Ihr Repository forken kann, kann daher Befehle vorschlagen, die auf Ihrem Rechner ausgeführt werden. Die standardmäßige Bestätigungsabfrage gilt nur für Mitwirkende, deren Commit oder Pull Request noch nie in das Repository übernommen wurde. Wenn Sie einen Runner an ein öffentliches Repository anbinden, deaktivieren Sie darauf Workflows für Pull Requests aus Forks, bewahren Sie keine anderen Daten auf diesem Server auf und setzen Sie den Rechner regelmäßig neu auf.

Warum schlägt die Registrierung mit Http response code: NotFound fehl?

Der Registrierungaufruf antwortet mit NotFound, wenn die Berechtigung nicht stimmt, und nicht nur bei einer falschen URL. Dadurch ist die Meldung irreführend. Registrierungstoken laufen eine Stunde nach ihrer Anzeige ab. Ein Personal Access Token wird für diesen Aufruf nicht akzeptiert. Öffnen Sie erneut Settings, Actions, Runners, New self-hosted runner, kopieren Sie das neue Token und prüfen Sie, ob der Wert --url auf ein Repository verweist, für das Sie Administratorrechte haben.