Referenzen zu selbstgehosteten Runnern

Hier findest du Informationen zum Einrichten und Verwenden von selbstgehosteten Runnern.

In diesem Artikel

Anforderungen für selbst-gehostete Runner-Maschinen

Du kannst jeden Computer als selbstgehosteten Runner verwenden, solange er die folgenden Anforderungen erfüllt:

  • Du kannst die Anwendung für selbst-gehostete Runner auf dem Rechner installieren und ausführen. Siehe Unterstützte Betriebssysteme und Unterstützte Prozessorarchitekturen.
  • Die Maschine kann mit GitHub Actions kommunizieren.
  • Der Rechner verfügt über genügend Hardwareressourcen für den Typ der Workflows, den du ausführen möchtest. Die Anwendung für selbst-gehostete Runner selbst erfordert nur minimale Ressourcen.
  • Wenn du Workflows ausführen willst, die Docker-Container-Aktionen oder Service-Container verwenden, brauchst du eine Linux-Maschine und Docker muss installiert sein.

Unterstützte Betriebssysteme

Linux

  • Red Hat Enterprise Linux 8 oder höher
  • CentOS 8 oder höher
  • Oracle Linux 8 oder höher
  • Fedora 29 oder höher
  • Debian 10 oder höher
  • Ubuntu 20.04 oder höher
  • Linux Mint 20 oder höher
  • openSUSE 15.2 oder höher
  • SUSE Enterprise Linux (SLES) 15 SP2 oder höher

Windows

  • Windows 10 64-Bit
  • Windows 11, 64 Bit
  • Windows Server 2016 (64 Bit)
  • Windows Server 2019 64-bit
  • Windows Server 2022 64-Bit

macOS

  • macOS 11.0 (Big Sur) oder höher

Unterstützte Prozessorarchitekturen

  • x64: Linux, macOS, Windows
  • ARM64 - Linux, macOS.
  • ARM32: Linux.

Routingrangfolge für selbstgehostete Runner

Wenn du einen Auftrag an einen selbstgehosteten Runner weiterleitest, sucht GitHub nach einem Runner, der mit den runs-on-Bezeichnungen und Gruppen des Auftrags übereinstimmt:

  • Wenn GitHub einen Online-Runner im Leerlauf findet, der mit den runs-on-Bezeichnungen und Gruppen des Auftrags übereinstimmt, wird der Auftrag dem Runner zugewiesen und zugesendet.
    • Wenn der Runner den zugewiesenen Auftrag nicht innerhalb von 60 Sekunden abholt, wird der Auftrag erneut in die Warteschlange gestellt, sodass er von einem neuen Runner angenommen werden kann.
  • Wenn GitHub keinen Online-Runner im Leerlauf findet, der mit den runs-on-Bezeichnungen und Gruppen des Auftrags übereinstimmt, bleibt der Auftrag in der Warteschlange, bis ein Runner online geschaltet wird.
  • Wenn der Auftrag länger als 24 Stunden in der Warteschlange bleibt, schlägt der Auftrag fehl.

Automatische Skalierung

Du kannst die Anzahl selbstgehosteter Runner in deiner Umgebung als Reaktion auf Webhookereignisse, die du mit einer bestimmten Bezeichnung erhältst, automatisch erhöhen oder verringern.

Unterstützte Lösungen für automatische Skalierung

Das Projekt actions-runner-controller (ARC) ist ein Kubernetes-basierter Runner-Autoskalierer. GitHub empfiehlt ARC, wenn das Team, das es bereitstellt, über Expertenwissen und -erfahrung verfügt.

Weitere Informationen findest du unter Actions Runner Controller und Support for Actions Runner Controller.

Kurzlebige Runner für die automatische Skalierung

GitHub empfiehlt die Implementierung der automatischen Skalierung mit kurzlebigen selbstgehosteten Runnern. Die automatische Skalierung mit beständigen selbstgehosteten Runnern wird nicht empfohlen. In bestimmten Fällen kann GitHub nicht garantieren, dass Aufträge keinen beständigen Runnern zugewiesen werden, während sie heruntergefahren werden. Bei kurzlebigen Runnern kann dies garantiert werden, da GitHub nur einen Auftrag pro Runner zuweist.

Mit diesem Ansatz kannst du deine Runner als kurzlebige Systeme verwalten, da du die Automatisierung dafür verwenden kannst, eine bereinigte Umgebung für jeden Auftrag bereitzustellen. Dadurch kann die Gefährdung von vertraulichen Ressourcen aus vorherigen Aufträgen begrenzt und auch das Risiko der Kompromittierung eines Runners, der neue Aufträge erhält, verringert werden.

Warnung

Die Runner-Anwendungsprotokolldateien für kurzlebige Runner müssen zur Problembehandlung und Diagnose an eine externe Protokollspeicherlösung weitergeleitet werden. Es ist zwar nicht erforderlich, dass kurzlebige Runner bereitgestellt werden, GitHub empfiehlt jedoch, sicherzustellen, dass Runner-Protokolle extern weitergeleitet und beibehalten werden, bevor sie eine kurzlebige Autokalierungslösung in einer Produktionsumgebung bereitstellen. Weitere Informationen finden Sie unter Überwachen und Behandeln von Problemen mit selbstgehosteten Runnern.

Wenn du deiner Umgebung einen kurzlebigen Runner hinzufügen möchtest, füge den --ephemeral-Parameter beim Registrieren deines Runners mit config.sh ein. Beispiel:

./config.sh --url https://github.com/octo-org --token example-token --ephemeral

Der GitHub Actions-Dienst hebt die Registrierung des Runners automatisch auf, nachdem ein Auftrag verarbeitet wurde. Anschließend kannst du deine eigene Automatisierung erstellen, die den Runner löscht, sobald die Registrierung aufgehoben wurde.

Hinweis

Wenn ein Auftrag für eine bestimmte Art von Runner gekennzeichnet ist, aber kein passender Runner verfügbar ist, schlägt der Auftrag nicht sofort in der Warteschlange fehl. Stattdessen bleibt der Auftrag bis zum Ablauf des Timeoutzeitraums von 24 Stunden in der Warteschlange.

Alternativ kannst du mit der REST-API kurzlebige Just-In-Time-Runner erstellen. Weitere Informationen finden Sie unter REST-API-Endpunkte für selbst gehostete Runner.

Softwareupdates für selbstgehostete Runner

Standardmäßig werden Softwareupdates für selbstgehostete Runner automatisch ausgeführt, wenn eine neue Version der Runnersoftware verfügbar ist. Wenn du kurzlebige Runner in Containern verwendest, kann dies bei der Veröffentlichung einer neuen Runnerversion zu wiederholten Softwareupdates führen. Durch das Deaktivieren automatischer Updates kannst du die Runnerversion im Containerimage direkt zum gewünschten Zeitpunkt aktualisieren.

Um automatische Softwareupdates zu deaktivieren und sie selbst zu installieren, musst du das Flag --disableupdate beim Registrieren deines Runners mit config.sh angeben. Beispiel:

./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate

Auch wenn du automatische Updates deaktivierst, musst du deine Runnerversion regelmäßig aktualisieren. Aufgrund der neuen Funktion in GitHub Actions müssen sowohl am GitHub Actions-Dienst als auch an der Runnersoftware Änderungen vorgenommen werden. Ohne ein Softwareupdate kann der Runner möglicherweise keine Aufträge verarbeiten, bei denen die neuen Features in GitHub Actions verwendet werden.

Wenn du automatische Updates deaktivierst, musst du deine Runnerversion innerhalb von 30 Tagen nach der Veröffentlichung einer neuen Version aktualisieren. Du solltest die Benachrichtigungen zu Releases im actions/runner-Repository abonnieren. Weitere Informationen finden Sie unter Benachrichtigungen konfigurieren.

Anweisungen zum Installieren der neuesten Runnerversion findest du in den Installationsanweisungen für das neueste Release.

Warnung

Alle Updates, die für die Software veröffentlicht werden, einschließlich Haupt-, Neben- oder Patch-Versionen, werden als verfügbares Update betrachtet. Wenn Sie innerhalb von 30 Tagen kein Softwareupdate durchführen, reiht der GitHub Actions-Dienst keine Aufträge in die Warteschlange Ihres Runners ein. Wenn ein kritisches Sicherheitsupdate durchgeführt werden muss, reiht der GitHub Actions-Dienst keine Aufträge in die Warteschlange deines Runners ein, bis dieser aktualisiert wurde.

Webhooks für die automatische Skalierung

Du kannst mithilfe der vom workflow_job-Webhook empfangenen Nutzdaten deine eigene Umgebung für die automatische Skalierung erstellen. Dieser Webhook ist auf Repository-, Organisations- und Unternehmensebene verfügbar, und die Nutzdaten für dieses Ereignis enthalten einen action-Schlüssel, der den Phasen des Lebenszyklus eines Workflowauftrags entspricht, z. B. wenn Aufträge queued, in_progress und completed sind. Anschließend musst du deine eigene Skalierungsautomatisierung als Reaktion auf diese Webhooknutzdaten erstellen.

Authentifizierungsanforderungen

Du kannst selbstgehostete Runner für Repositorys und Organisationen mit der API registrieren und löschen. Deine Implementierung für die automatische Skalierung kann ein Zugriffstoken oder eine GitHub-App verwenden, um sich bei der API zu authentifizieren.

Dein Zugriffstoken benötigt den folgenden Geltungsbereich:

Um sich mithilfe einer GitHub-App zu authentifizieren, muss sie über die folgenden Berechtigungen verfügen:

  • Weise für Repositorys die Berechtigung administration zu.
  • Weise für Organisationen die Berechtigung organization_self_hosted_runners zu.

Du kannst selbstgehostete Runner für Unternehmen mithilfe der API registrieren und löschen. Die Implementierung zur automatischen Skalierung kann ein Zugriffstoken verwenden, um sich bei der API zu authentifizieren.

Dein Zugriffstoken benötigt den manage_runners:enterprise-Geltungsbereich.

Kommunikation

Selbstgehostete Runner stellen eine Verbindung mit deine GitHub Enterprise Server-Instanz her, um Auftragszuweisungen zu empfangen und neue Versionen der Runneranwendung herunterzuladen.

Die GitHub Actions Läufer-Anwendung ist Open Source. Du kannst im Runner-Repository mitwirken und Dateiprobleme einreichen. Wenn eine neue Version veröffentlicht wird, wird die Runner-Anwendung innerhalb von 24 Stunden automatisch aktualisiert.

Anforderungen an die Kommunikation mit deine GitHub Enterprise Server-Instanz

  • Der selbstgehostete Runner muss auf dem Hostcomputer ausgeführt werden, um GitHub Actions-Aufträge zu akzeptieren und auszuführen.
  • GitHub Enterprise Server muss eingehende Verbindungen von deinen Runnern über HTTP(S) im Hostnamen und der API-Unterdomäne von deine GitHub Enterprise Server-Instanz akzeptieren. Außerdem müssen deine Runner ausgehende Verbindungen mit dem Hostnamen und der API-Unterdomäne von deine GitHub Enterprise Server-Instanz über HTTP(S) zulassen.
  • Damit das Zwischenspeichern funktioniert, muss der Runner mit dem Blobspeicher kommunizieren und Inhalte direkt von diesem herunterladen können.

Kommunikation mit GitHub.com

Selbstgehostete Runner müssen keine Verbindung mit GitHub.com herstellen, es sei denn, du hast den automatischen Zugriff auf GitHub.com-Aktionen für GitHub Enterprise Server aktiviert. Weitere Informationen finden Sie unter Informationen zum Verwenden von Aktionen in deinem Unternehmen.

Wenn dein Runner eine Verbindung mit GitHub.com herstellen soll, muss der Hostcomputer in der Lage sein, ausgehende HTTP-Verbindungen über Port 80 oder HTTPS-Verbindungen über Port 443 herzustellen. Um die Konnektivität über HTTPS sicherzustellen, konfiguriere TLS für GitHub Enterprise Server. Weitere Informationen findest du unter TLS konfigurieren.

Wenn du den automatischen Zugriff auf GitHub.com-Aktionen aktiviert hast, wird der selbstgehostete Runner direkt mit GitHub.com verbunden, um Aktionen herunterzuladen. Du musst sicherstellen, dass der Rechner über den entsprechenden Netzwerkzugriff verfügt, um mit den nachfolgend aufgelisteten GitHub-URLs zu kommunizieren.

Shell
github.com
api.github.com
codeload.github.com
pkg.actions.githubusercontent.com

Du kannst die REST-API verwenden, um Metainformationen über GitHub abzurufen, einschließlich der IP-Adressen und Domänendetails von GitHub-Diensten. Der Abschnitt actions_inbound der API unterstützt sowohl vollqualifizierte als auch Platzhalterdomänen. Vollqualifizierte Domänen geben einen vollständigen Domänennamen (z. B. example.github.com) an, während Platzhalterdomänen * verwenden, um mehrere mögliche Unterdomänen darzustellen (z. B. *.github.com). Nachfolgend findest du ein Beispiel für die Anforderungen an selbstgehostete Runner mit Platzhalterdomänen. Weitere Informationen finden Sie unter REST-API-Endpunkte für Metadaten.

Shell
github.com
*.github.com
*.githubusercontent.com
ghcr.io

Hinweis

Einige der aufgeführten Domänen werden mithilfe von CNAME-Einträgen konfiguriert. Für bestimmte Firewalls musst du Regeln möglicherweise rekursiv für alle CNAME-Einträge hinzufügen. Beachte, dass sich die CNAME-Einträge in Zukunft ändern können und dass nur die aufgeführten Domänen konstant bleiben.