Documentation de référence relative aux runners auto-hébergés

Configuration requise pour les machines d’exécuteur auto-hébergé

Une machine peut être utilisée comme runner auto-hébergé dès lors qu’elle satisfait aux exigences suivantes :

Vous pouvez installer et exécuter l’application d’exécuteur auto-hébergée sur la machine. Voir Systèmes d'exploitation pris en charge et Architectures de processeurs prises en charge.
La machine peut communiquer avec GitHub Actions.
La machine dispose de suffisamment de ressources matérielles pour le type de workflows que vous envisagez d’exécuter. L’application d’exécuteur auto-hébergé elle-même nécessite uniquement des ressources minimales.
Si vous souhaitez exécuter des workflows qui utilisent des actions de conteneur Docker ou des conteneurs de service, vous devez utiliser une machine Linux et Docker doit être installé.

Systèmes d’exploitation pris en charge

Linux

Red Hat Enterprise Linux 8 ou version ultérieure
CentOS 8 ou version ultérieure
Oracle Linux 8 ou version ultérieure
Fedora 29 ou version ultérieure
Debian 10 ou version ultérieure
Ubuntu 20.04 ou version ultérieure
Linux Mint 20 ou version ultérieure
openSUSE 15.2 ou version ultérieure
SUSE Enterprise Linux (SLES) 15 SP2 ou version ultérieure

Windows

Windows 10 64 bits
Windows 11 64 bits
Windows Server 2016 64 bits
Windows Server 2019 64-bit
Windows Server 2022 64 bits

macOS

macOS 11.0 (Big Sur) ou version ultérieure

Architectures de processeurs prises en charge

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

Priorité de routage pour les exécuteurs auto-hébergés

Lors du routage d’un travail vers un runner auto-hébergé, GitHub recherche un runner correspondant aux labels et groupes runs-on :

Si GitHub trouve un runner en ligne et inactif qui correspond aux étiquettes et aux groupes runs-on du travail, le travail est ensuite affecté et envoyé au runner.
- Si l’exécuteur ne récupère pas le travail affecté dans un délai de 60 secondes, le travail est remis en file d’attente afin qu’un nouvel exécuteur puisse l’accepter.
Si GitHub ne trouve pas de runner en ligne et inactif correspondant aux étiquettes et aux groupes runs-on du travail, le travail reste en file d’attente jusqu’à ce qu’un runner soit en ligne.
Si le travail reste en file d’attente plus de 24 heures, il échoue.

La mise à l’échelle automatique vous permet d’ajuster dynamiquement le nombre d’exécuteurs auto-hébergés en fonction de la demande. Cela permet d’optimiser l’utilisation des ressources et de garantir une capacité d’exécution suffisante pendant les heures de pointe tout en réduisant les coûts pendant les périodes de faible activité. Plusieurs méthodes permettent de mettre en place une mise à l’échelle automatique pour les runners auto-hébergés, chacune impliquant des compromis distincts en matière de complexité, de fiabilité et de réactivité.

Actions Runner Controller

Actions Runner Controller (ARC) constitue l’implémentation de référence des API de groupes de machines virtuelles identiques de GitHub et la solution basée sur Kubernetes recommandée pour la mise à l’échelle automatique des runners auto-hébergés. ARC fournit une solution complète de mise à l’échelle automatique prête pour la production pour les équipes qui s’exécutent GitHub Actions dans des environnements Kubernetes.

GitHub recommande ARC pour les organisations disposant d’une infrastructure Kubernetes et d’équipes disposant d’une expertise Kubernetes. ARC gère le cycle de vie complet des agents au sein de votre cluster, de la configuration à l’exécution des tâches jusqu'au nettoyage.

Pour plus d’informations, consultez « Actions Runner Controller » et « Prise en charge d'Actions Runner Controller ».

GitHub Actions Client Runner Scale Set

Le client GitHub Actions Runner Scale Set est un module go autonome qui permet aux équipes de plateforme, aux intégrateurs et aux fournisseurs d’infrastructure de créer des solutions de mise à l’échelle automatique personnalisées pour GitHub Actions exécuteurs sur des machines virtuelles, des conteneurs, une infrastructure locale et des services cloud, avec prise en charge des plateformes Windows, Linux et macOS.

Le client orchestre les interactions avec les API de groupes de machines virtuelles identiques de GitHub, tandis que vous restez responsable du provisionnement de l’infrastructure. Vous déterminez les modalités de création, de mise à l’échelle et de suppression des runners, et vous configurez ces derniers avec plusieurs étiquettes afin d’assurer un routage et un ciblage flexibles des tâches. Cela permet aux organisations de contrôler de façon granulaire la gestion du cycle de vie des agents et les données de télémétrie en temps réel pour l’exécution des tâches.

Le client est conçu pour fonctionner de manière prête à l’emploi avec des configurations de base, ce qui permet aux équipes d’implémenter rapidement la mise à l’échelle automatique. Toutefois, sa véritable puissance réside dans sa flexibilité : le client est conçu pour être étendu et personnalisé pour répondre aux exigences spécifiques de l’infrastructure, aux contraintes de conformité et aux flux de travail opérationnels de chaque organisation. Que vous ayez besoin d’une logique de mise à l’échelle simple ou de stratégies d’approvisionnement multi-environnement complexes, le client s’adapte à vos besoins.

Le client GitHub Actions Runner Scale Set est un projet open source. Le référentiel actions/scaleset contient le code source complet, la documentation complète et des exemples pratiques pour vous aider à commencer. Vous trouverez des guides d’implémentation, des exemples de configurations pour différents scénarios d’infrastructure et des architectures de référence illustrant comment intégrer le client à différents systèmes d’approvisionnement. Le référentiel inclut également des instructions de contribution pour les équipes intéressées par l’extension du client ou le partage de leurs modèles de mise à l’échelle automatique avec la communauté.

Note: Le client de groupe identique Runner n’est pas un remplacement pour Actions Runner Controller (ARC), qui reste l’implémentation de référence des API de groupe identique et la solution Kubernetes recommandée pour les exécuteurs de mise à l’échelle automatique. Ce client constitue plutôt un outil complémentaire permettant d’interagir avec ces mêmes API de scale set afin de concevoir des solutions personnalisées de mise à l’échelle automatique en dehors de Kubernetes.

Runners éphémères pour la mise à l’échelle automatique

GitHub recommande d’implémenter la mise à l’échelle automatique avec des exécuteurs auto-hébergés éphémères ; la mise à l’échelle automatique avec des exécuteurs auto-hébergés persistants n’est pas recommandée. Dans certains cas, GitHub ne peut pas garantir que les tâches ne sont pas attribuées à des runners persistants pendant leur arrêt. Avec les runners éphémères, cela peut être garanti, car GitHub n’affecte qu’un seul travail à un runner.

Cette approche vous permet de gérer vos exécuteurs en tant que systèmes éphémères, car vous pouvez utiliser l’automatisation pour fournir un environnement propre pour chaque travail. Cela permet de limiter l’exposition de toutes les ressources sensibles issues des travaux précédents, et permet également d’atténuer le risque qu’un agent compromis reçoive de nouveaux travaux.

Avertissement

Les journaux d’activité de l’application des runners éphémères doivent être transférés vers une solution externe de stockage de logs à des fins d’analyse et de diagnostic. Bien qu’il ne soit pas nécessaire de déployer des runners éphémères, GitHub recommande de s’assurer que les journaux des runners sont transmis et conservés dans un système externe avant de déployer une solution de mise à l’échelle automatique des runners éphémères dans un environnement de production. Pour plus d’informations, consultez « Surveillance des exécuteurs auto-hébergés et résolution des problèmes ».

Pour ajouter un exécuteur éphémère à votre environnement, incluez le paramètre --ephemeral lors de l’inscription de votre exécuteur à l’aide de config.sh. Par exemple :

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

Le service GitHub Actions désenregistrera automatiquement le runner après avoir traité une tâche. Vous pouvez ensuite créer votre propre automatisation qui efface l’exécuteur une fois qu’il a été désinscrit.

Remarque

Si une tâche est étiquetée pour un certain type d’exécuteur, mais qu’aucun exécutant de ce type n’est disponible, la tâche n’échoue pas immédiatement lors de la mise en file d’attente. Au lieu de cela, le travail reste en file d’attente jusqu’à ce que la période d’expiration de 24 heures expire.

Vous pouvez également créer des exécuteurs à la demande et éphémères à l’aide de l’API REST. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les exécuteurs auto-hébergés ».

Mises à jour logicielles des runners auto-hébergés

Par défaut, les exécuteurs auto-hébergés effectuent automatiquement une mise à jour logicielle chaque fois qu’une nouvelle version du logiciel d’exécuteur est disponible. Si vous utilisez des exécuteurs éphémères dans des conteneurs, cela peut entraîner des mises à jour logicielles répétées lorsqu’une nouvelle version de l’exécuteur est publiée. La désactivation des mises à jour automatiques vous permet de mettre à jour la version de l’exécuteur sur l’image conteneur directement selon votre propre calendrier.

Pour désactiver les mises à jour logicielles automatiques et installer vous-même les mises à jour logicielles, spécifiez le drapeau --disableupdate lorsque vous enregistrez votre coureur à l'aide de config.sh. Par exemple :

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

Si vous désactivez les mises à jour automatiques, vous devez toujours mettre régulièrement à jour votre version d’exécuteur. De nouvelles fonctionnalités dans GitHub Actions nécessitent des modifications à la fois du service GitHub Actions_et_ du logiciel runner. L’exécuteur peut ne pas être en mesure de traiter correctement les tâches qui tirent parti des nouvelles fonctionnalités de GitHub Actions sans une mise à jour du logiciel.

Si vous désactivez les mises à jour automatiques, vous serez tenu de mettre à jour votre version de l’exécuteur dans les 30 jours suivant la mise à disposition d’une nouvelle version. Vous avez la possibilité de vous abonner aux notifications relatives aux versions dans le référentiel actions/runner. Pour plus d’informations, consultez « Configuration des notifications ».

Pour obtenir des instructions sur la façon d’installer la dernière version de l’exécuteur, consultez les instructions d’installation de la dernière version.

Avertissement

Toutes les mises à jour publiées pour le logiciel, y compris les versions majeures, mineures ou correctives, sont considérées comme une mise à jour disponible. Si vous n’effectuez pas de mise à jour de logiciel dans les 30 jours, le service GitHub Actions ne met pas en file d’attente les travaux pour votre exécuteur. En outre, si une mise à jour de sécurité critique est requise, le service GitHub Actions ne met pas en file d’attente les travaux pour votre exécuteur tant qu’il n’a pas été mis à jour.

Webhooks pour la mise à l’échelle automatique

Vous pouvez créer votre propre environnement de mise à l’échelle automatique à l’aide des charges utiles reçues du webhook workflow_job. Ce webhook est disponible au niveau du dépôt, de l’organisation et de la grande entreprise, et la charge utile de cet événement contient une clé action qui correspond aux étapes du cycle de vie d’un travail de workflow. Par exemple, lorsque les travaux sont queued, in_progress et completed. Vous devez ensuite créer votre propre automatisation de mise à l’échelle en réponse à ces charges utiles de webhook.

Pour plus d'informations sur le workflow_job webhook, voir Événements et charges utiles du webhook.
Pour savoir comment utiliser les webhooks, voir Documentation sur les webhooks.

Note: Cette approche s’appuie sur la chronologie de la livraison de webhooks pour prendre des décisions de mise à l’échelle, ce qui peut introduire des retards et des préoccupations de fiabilité. Envisagez d’utiliser le contrôleur d'Actions ou le client de groupe de mise à l’échelle pour des scénarios de mise à l’échelle automatique d'un volume plus important.

Exigences relatives à l’authentification

Vous pouvez inscrire et supprimer des exécuteurs auto-hébergés de dépôt ou d’organisation à l’aide de l’API. Pour vous authentifier auprès de l’API, votre implémentation de mise à l’échelle automatique peut utiliser un jeton d’accès ou une GitHub application.

Votre jeton d’accès nécessite l’étendue suivante :

Pour les dépôts privés, utilisez un jeton d’accès avec la portée repo.
Pour les référentiels publics, utilisez un jeton d’accès disposant de l’étendue public_repo.
Pour les organisations, utilisez un jeton d’accès disposant de l’étendue admin:org.

Pour vous authentifier à l’aide d’une GitHub application, vous devez lui attribuer les autorisations suivantes :

Pour les dépôts, attribuez l’autorisation administration.
Pour les organisations, attribuez l’autorisation organization_self_hosted_runners.

Vous pouvez inscrire et supprimer des exécuteurs auto-hébergés d'entreprise à l’aide de l’API. Pour vous authentifier auprès de l’API, votre implémentation de mise à l’échelle automatique peut utiliser un jeton d’accès.

Votre jeton d’accès nécessite l’étendue manage_runners:enterprise.

Communication

Les runners auto-hébergés se connectent à votre instance GitHub Enterprise Server pour recevoir des attributions de tâches et télécharger de nouvelles versions de l’application du runner.

L’exécuteur GitHub Actions est une application open source. Vous pouvez signaler et contribuer à résoudre des problèmes dans le référentiel de l’exécuteur. Lorsqu’une nouvelle version est publiée, l’application d’exécuteur est automatiquement mise à jour dans les 24 heures.

Conditions requises pour la communicationvotre instance GitHub Enterprise Server

L’application de runner auto-hébergé doit s’exécuter sur l’ordinateur hôte pour accepter et exécuter des travaux GitHub Actions.
GitHub Enterprise Server doit accepter les connexions entrantes de vos runners via HTTP(S) au niveau du nom d’hôte et du sous-domaine d’API de votre instance GitHub Enterprise Server, et vos runners doivent autoriser les connexions sortantes via HTTP(S) vers le nom d’hôte et le sous-domaine d’API de votre instance GitHub Enterprise Server.
Pour que la mise en cache fonctionne, l’exécuteur doit pouvoir communiquer avec le stockage blob et télécharger directement du contenu à partir de celui-ci.

Communication avec GitHub.com

Les runners auto-hébergés n’ont pas besoin de se connecter à GitHub.com sauf si vous avez activé l’accès automatique aux actions GitHub.com pour GitHub Enterprise Server. Pour plus d’informations, consultez « À propos de l’utilisation d’actions dans votre entreprise ».

Si vous souhaitez que votre exécuteur se connecte GitHub.com, l’ordinateur hôte doit être en mesure d’établir des connexions HTTP sortantes sur le port 80 ou des connexions HTTPS sur le port 443. Pour garantir la connectivité via HTTPS, configurez TLS pour GitHub Enterprise Server. Consultez Configuration de TLS.

Si vous avez activé l’accès automatique aux actions GitHub.com, le runner auto-hébergé se connectera directement à GitHub.com pour y télécharger des actions. Vous devez vous assurer que l’ordinateur dispose de l’accès réseau approprié pour communiquer avec les GitHub URL répertoriées ci-dessous.

Shell

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

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

Vous pouvez utiliser l’API REST pour obtenir des métadonnées sur GitHub, y compris les adresses IP et les détails du domaine pour GitHub les services. La section actions_inbound de l’API prend en charge à la fois les domaines pleinement qualifiés et les domaines avec caractères génériques. Les domaines complets spécifient un nom de domaine complet (par exemple, example.github.com), tandis que les domaines avec caractères génériques utilisent un * pour représenter plusieurs sous-domaines possibles (par exemple, *.github.com). Vous trouverez ci-dessous un exemple illustrant les exigences applicables aux runners auto-hébergés utilisant des caractères génériques. Pour plus d’informations, consultez « Points de terminaison d’API REST pour les métadonnées ».