Referenzen zu selbstgehosteten Runnern

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

Unterstützte Prozessorarchitekturen

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

Routingrangfolge für selbstgehostete Runner

Wenn ein Auftrag an einen selbstgehosteten Runner weitergeleitet wird, sucht GitHub nach einem Runner, der den runs-on Labels und Gruppen des Auftrags entspricht:

Wenn GitHub einen online und inaktiven Runner findet, der den runs-on Labels und Gruppen des Auftrags entspricht, wird der Auftrag zugewiesen und an den Runner gesendet.
- 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 und inaktiven Runner findet, der zu den Labels und Gruppen des Jobs runs-on passt, bleibt der Job in der Warteschlange, bis ein Runner online kommt.
Wenn der Auftrag länger als 24 Stunden in der Warteschlange bleibt, schlägt der Auftrag fehl.

Mit der automatischen Skalierung können Sie die Anzahl der selbst gehosteten Läufer basierend auf Bedarf dynamisch anpassen. Dadurch wird die Ressourcenauslastung optimiert und eine ausreichende Läuferkapazität während der Spitzenzeiten gewährleistet, während die Kosten in Zeiten geringer Aktivität reduziert werden. Es gibt mehrere Ansätze zur Implementierung der automatischen Skalierung für selbst gehostete Läufer, die jeweils verschiedene Kompromisse hinsichtlich Komplexität, Zuverlässigkeit und Reaktionsfähigkeit aufweisen.

Actions Runner Controller

Actions Runner Controller (ARC) ist die Referenzimplementierung von GitHubs Scale-Set-APIs und die empfohlene Kubernetes-basierte Lösung für die automatische Skalierung selbstgehosteter Runner. ARC bietet eine vollständige, produktionsreife Lösung zur automatischen Skalierung für Teams, die GitHub Actions in Kubernetes-Umgebungen ausführen.

GitHub empfiehlt ARC für Organisationen mit Kubernetes-Infrastruktur und Teams mit Kubernetes-Know-how. ARC behandelt den vollständigen Lebenszyklus von Runnern innerhalb Ihres Clusters, von der Bereitstellung über die Auftragsausführung bis zur Bereinigung.

Weitere Informationen findest du unter Actions Runner Controller (Steuerung für Aktionsläufer) und Unterstützung für Actions Runner Controller.

GitHub Actions Runner-Skalierungsgruppenclient

Der GitHub Actions Runner Scale Set Client ist ein eigenständiges Go-basiertes Modul, mit dem Plattformteams, Integratoren und Infrastrukturanbieter benutzerdefinierte Autoscaling-Lösungen für GitHub Actions Runner auf VMs, in Containern, in On-Premises-Infrastrukturen und in Cloud-Diensten erstellen können, mit Unterstützung für Windows-, Linux- und macOS-Plattformen.

Der Client orchestriert GitHub API-Interaktionen für Skalierungsgruppen, während die Bereitstellung der Infrastruktur Ihnen überlassen bleibt. Sie legen fest, wie Runner erstellt, skaliert und zerstört werden, und konfigurieren Runner mit mehreren Labels für flexibles Routing und die gezielte Zuordnung von Aufgaben. Dadurch erhalten Organisationen eine granulare Kontrolle über das Management des Lebenszyklus von Runnern und Echtzeit-Telemetrie für die Auftragsausführung.

Der Client ist so konzipiert, dass er sofort mit grundlegenden Konfigurationen funktioniert, sodass Teams die automatische Skalierung schnell implementieren können. Die wahre Leistungsfähigkeit liegt jedoch in seiner Flexibilität – der Client ist so aufgebaut, dass er erweitert und angepasst wird, um die spezifischen Infrastrukturanforderungen, Complianceeinschränkungen und betrieblichen Workflows der einzelnen Organisation zu erfüllen. Ganz gleich, ob Sie einfache Skalierungslogik oder komplexe Bereitstellungsstrategien für mehrere Umgebungen benötigen, passt sich der Client an Ihre Anforderungen an.

Der GitHub Actions Runner Scale Set Client ist ein Open Source Projekt. Das Repository "actions/scaleset" enthält den vollständigen Quellcode, umfassende Dokumentation und praktische Beispiele, die Ihnen bei den ersten Schritten helfen. Sie finden Implementierungshandbücher, Beispielkonfigurationen für verschiedene Infrastrukturszenarien und Referenzarchitekturen, die zeigen, wie der Client in verschiedene Bereitstellungssysteme integriert werden kann. Das Repository enthält auch Richtlinien für Teams, die daran interessiert sind, den Client zu erweitern oder ihre automatischen Skalierungsmuster mit der Community zu teilen.

Hinweis: Der Runner Scale Set Client ist kein Ersatz für Actions Runner Controller (ARC), der die Referenzimplementierung der Skalierungssatz-APIs und die empfohlene Kubernetes-Lösung für automatische Skalierungsläufer bleibt. Stattdessen ist der Client ein ergänzendes Tool, um über die gleichen Scale-Set-APIs individuelle Autoscaling-Lösungen außerhalb von Kubernetes zu erstellen.

Temporäre Runner für die automatische Skalierung

GitHub empfiehlt, die automatische Skalierung mit kurzlebigen selbst gehosteten Läufern zu implementieren; Die automatische Skalierung mit dauerhaften selbst gehosteten Läufern wird nicht empfohlen. In bestimmten Fällen kann GitHub nicht gewährleisten, dass Jobs nicht persistenten Runnern zugewiesen werden, während sie heruntergefahren werden. Mit kurzlebigen Runnern kann dies garantiert werden, da GitHub jedem Runner nur einen Job 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, ephemere Runner bereitzustellen, GitHub empfiehlt jedoch, sicherzustellen, dass Runner-Protokolle extern weitergeleitet und gespeichert werden, bevor eine Lösung zur automatischen Skalierung ephemerer Runner in einer Produktionsumgebung eingesetzt wird. Weitere Informationen finden Sie unter Überwachen und Beheben 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 wird dann den Läufer automatisch deregistrieren, nachdem er einen Auftrag verarbeitet hat. 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 beim Einreihen in die Warteschlange nicht sofort 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. Neue Funktionalität in GitHub Actions erfordert Änderungen sowohl am GitHub Actions-Dienst als auch an der Runner-Software. Der Runner kann Jobs, die neue Funktionen in GitHub Actions nutzen, ohne ein Software-Update möglicherweise nicht korrekt verarbeiten.

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 Patchversionen, 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 Webhook-Datenpakete erstellen.

Weitere Informationen zum workflow_job-Webhook findest du unter Webhook-Ereignisse und Webhook-Nutzlasten.
Weitere Informationen zum Arbeiten mit Webhooks findest du unter Webhooks-Dokumentation.

Hinweis: Dieser Ansatz verlässt sich auf die Pünktlichkeit der Webhook-Übermittlung, um Skalierungsentscheidungen zu treffen, was zu Verzögerungen und Zuverlässigkeitsproblemen führen kann. Erwägen Sie die Verwendung des Actions Controllers oder des Skalenset-Clients für automatische Skalierungsszenarien mit großem Volumen.

Authentifizierungsanforderungen

Du kannst selbstgehostete Runner für Repositorys und Organisationen mit der API registrieren und löschen. Um sich bei der API zu authentifizieren, kann Ihre automatische Skalierungsimplementierung ein Zugriffstoken oder eine GitHub App verwenden.

Dein Zugriffstoken benötigt den folgenden Geltungsbereich:

Verwende bei privaten Repositorys ein Zugriffstoken mit dem repo-Geltungsbereich.
Verwende bei öffentlichen Repositorys ein Zugriffstoken mit dem public_repo-Geltungsbereich:
Verwende bei Organisationen ein Zugriffstoken mit dem admin:org-Geltungsbereich.

Um sich mit einer GitHub App zu authentifizieren, muss ihnen die folgenden Berechtigungen zugewiesen werden:

Weise für Repositorys die Berechtigung administration zu.
Weise die Berechtigung organization_self_hosted_runners für Organisationen 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 verbinden sich mit deine GitHub Enterprise Server-Instanz, um Jobzuweisungen zu empfangen und neue Versionen der Runner-Anwendung 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 Kommunikationdeine GitHub Enterprise Server-Instanz

Die selbst gehostete Runner-Anwendung muss auf dem Hostcomputer ausgeführt werden, um Aufträge anzunehmen und auszuführen GitHub Actions .
GitHub Enterprise Server muss eingehende Verbindungen von Ihren Runnern über HTTP(S) über den Hostnamen und die API-Subdomain von deine GitHub Enterprise Server-Instanz akzeptieren, und Ihre Runner müssen ausgehende Verbindungen über HTTP(S) zum Hostnamen und zur API-Subdomain von deine GitHub Enterprise Server-Instanz 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 zu GitHub.com herstellen, es sei denn, Sie haben 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 Ihr Runner eine Verbindung mit GitHub.com herstellen soll, muss die Hostmaschine ausgehende HTTP-Verbindungen über Port 80 oder HTTPS-Verbindungen über Port 443 herstellen können. Um die Konnektivität über HTTPS sicherzustellen, konfigurieren Sie TLS für GitHub Enterprise Server. Weitere Informationen findest du unter TLS konfigurieren.

Wenn Sie den automatischen Zugriff auf Aktionen von GitHub.com aktiviert haben, stellt der selbstgehostete Runner eine direkte Verbindung zu GitHub.com her, um Aktionen herunterzuladen. Sie müssen sicherstellen, dass der Computer über den entsprechenden Netzwerkzugriff verfügt, um mit den GitHub unten aufgeführten URLs zu kommunizieren.

Shell

github.com
api.github.com
codeload.github.com

github.com
api.github.com
codeload.github.com

Sie können die REST-API verwenden, um Metainformationen GitHubzu erhalten, einschließlich der IP-Adressen und Domänendetails für GitHub Dienste. 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.