Documentation relative aux exécuteurs auto-hébergés

Vous trouverez dans cette section des indications concernant la configuration et l’exploitation des exécuteurs auto-hébergés.

Dans cet article

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

Il est possible d’utiliser une machine en tant qu'exécuteur 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 de l'acheminement d'un travail vers une unité d'exécution autonome, GitHub recherche une unité d'exécution correspondant aux libellés runs-on et aux groupes du travail :

  • Si GitHub détecte un exécuteur en ligne et inactif correspondant aux étiquettes et aux groupes runs-on du job, celui-ci lui est attribué et transmis.
    • 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 aucun exécuteur en ligne et inactif correspondant aux étiquettes et aux groupes runs-on du job, celui-ci demeure en attente jusqu’à ce qu’un exécuteur se connecte.
  • Si le travail reste en file d’attente plus de 24 heures, il échoue.

Mise à l’échelle automatique

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 la mise à l’échelle automatique des exécuteurs auto-hébergés, chacune impliquant des compromis 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 scale set de GitHub ainsi que la solution Kubernetes recommandée pour l’automatisation de la mise à l’échelle des exécuteurs auto-hébergés. ARC fournit une solution complète de mise à l’échelle automatique prête pour la production pour les équipes exécutant GitHub Actions dans les 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 de Scale Set pour les exécuteurs

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 compatibilité pour les plateformes Windows, Linux et macOS.

Le client coordonne les interactions avec l’API GitHub dédiée aux scale sets tout en vous laissant responsable du provisionnement de l’infrastructure. Vous déterminez les modalités de création, de mise à l’échelle et de suppression des exécuteurs, et vous les configurez à l’aide de plusieurs étiquettes afin de permettre un routage et un ciblage des tâches flexibles. 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 projet client GitHub Actions Runner Scale Set est 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é.

          **Remarque :** le client de scale set de runners ne se substitue pas à Actions Runner Controller (Arc), qui demeure l’implémentation de référence des API de scale set et la solution Kubernetes recommandée pour la mise à l’échelle automatique des exécuteurs. Il s’agit plutôt d’un outil complémentaire permettant d’interagir avec ces mêmes API de scale set afin de concevoir des solutions d’autoscaling personnalisées 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 peuvent pas garantir que les travaux ne sont pas affectés aux exécuteurs persistants pendant qu’ils sont arrêtés. Avec les runners éphémères, cela peut être garanti car GitHub affecte une seule tâche à 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 de l’application runner pour les exécuteurs éphémères doivent être redirigés vers une solution externe de stockage de logs afin de faciliter le dépannage et le diagnostic. Bien qu’il ne soit pas obligatoire de déployer des exécuteurs éphémères, GitHub recommande de s’assurer que les journaux d’exécuteurs sont transmis et conservés en externe avant de déployer une solution de mise à l’échelle automatique d’exécuteurs é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ésinscrit automatiquement l’exécuteur une fois qu’il a traité un travail. 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 exécuteurs 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. Une nouvelle fonctionnalité dans GitHub Actions nécessite des modifications dans le service GitHub Actions et le logiciel d’exécuteur. L’exécuteur peut ne pas être en mesure de traiter correctement les travaux qui exploitent de nouvelles fonctionnalités dans GitHub Actions sans mise à jour logicielle.

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 pouvez vous abonner aux notifications de publication 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.

          **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 application GitHub.

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 application GitHub, elle doit être affectée des 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 exécuteurs auto-hébergés établissent une connexion à votre instance GitHub Enterprise Server afin de recevoir les affectations de tâches et de télécharger les nouvelles versions de l’application 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 exécutrice se met automatiquement à jour dans les 24 heures.

Conditions requises pour la communication avec votre instance GitHub Enterprise Server

  • L’application Runner auto-hébergée doit être active sur la machine hôte afin d’accepter et d’exécuter les tâches GitHub Actions.
  • GitHub Enterprise Server doit accepter les connexions entrantes provenant de vos exécuteurs via HTTP(S) sur le nom d'hôte et le sous-domaine API de votre instance GitHub Enterprise Server, et vos exécuteurs doivent autoriser les connexions sortantes via HTTP(S) vers le nom d'hôte et le sous-domaine 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 exécuteurs auto-hébergés n’ont pas besoin d’établir de connexion à GitHub.com, sauf si vous avez activé l’accès automatique aux actions de 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, la machine hôte doit être capable 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, l’exécuteur auto-hébergé se connecte directement à GitHub.com pour télécharger les actions. Vous devez vous assurer que la machine dispose de l’accès réseau approprié pour communiquer avec les URL GitHub listées ci-dessous.

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

Vous pouvez utiliser l’API REST pour obtenir des métadonnées sur GitHub, notamment les adresses IP et les détails du domaine pour les services GitHub. 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 des 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 ».

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

Remarque

Certains des domaines listés sont configurés à l'aide d'enregistrements CNAME. Certains pare-feu peuvent nécessiter l'ajout de règles récursives pour tous les enregistrements CNAME. Notez que les enregistrements CNAME peuvent changer à l'avenir et que seuls les domaines listés resteront constants.