Référence des exécuteurs auto-hébergés

Recherchez des informations sur la configuration et l’utilisation d’exécuteurs auto-hébergés.

Dans cet article

Configurations requises pour les machines d’exécuteur auto-hébergé

Vous pouvez utiliser une machine comme runner auto-hébergé à condition qu'elle réponde 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 agents 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 trouve un exécutant en ligne et inactif qui correspond aux étiquettes et aux groupes du travailruns-on, le travail est alors assigné et envoyé à l'exécutant.
    • 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 d'exécutant en ligne et inactif qui corresponde aux étiquettes et aux groupes du travailruns-on, le travail restera en file d'attente jusqu'à ce qu'un exécutant se mette en ligne.
  • 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é. Il existe plusieurs approches pour implémenter la mise à l’échelle automatique pour les exécuteurs auto-hébergés, chaque approche présentant différents compromis en termes de complexité, de fiabilité et de réactivité.

Actions Runner Controller

Actions Runner Controller (ARC) est la référence en matière d'implémentation des API de lot d'GitHub et la solution recommandée basée sur Kubernetes pour l’autoscaling 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 Runner d'ensemble évolutif

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 orchestre les interactions avec l’API de GitHub pour les groupes de mise à l'échelle, tout en vous laissant la charge du provisionnement de l’infrastructure. Vous définissez la manière dont les agents sont créés, mis à l'échelle et détruits, et vous configurez les agents avec plusieurs étiquettes pour 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 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é.

          **Note :** Le client de l'ensemble de mise à l'échelle Runner n’est pas un remplacement pour Actions Runner Controller (ARC), qui reste l’implémentation de référence des API d'ensemble de mise à l'échelle et la solution Kubernetes recommandée pour les exécutants en mise à l'échelle automatique. Au lieu de cela, le client est un outil complémentaire permettant d’interagir avec les mêmes API de groupe identique pour créer des solutions de mise à l’échelle automatique personnalisées en dehors de Kubernetes.

Exécuteurs é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 travaux ne soient pas affectés par des exécuteurs persistants lorsqu'ils sont en cours d'arrêt. 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 tâche. 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 fichiers journaux des applications d'exécution pour les exécuteurs éphémères doivent être transmis à une solution de stockage de journaux externe à des fins de diagnostic et de dépannage. 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 en utilisant config.sh. Par exemple :

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

Le service GitHub Actions désenregistre automatiquement l’exécuteur après qu’il a traité une tâche. Vous pouvez ensuite créer votre propre automatisation qui supprime l’exécuteur après sa désinscription.

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 restera en file d'attente jusqu'à l'expiration du délai de 24 heures.

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 ».

Exécutez les mises à jour logicielles sur les 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 un délai de 30 jours après la mise à disposition d’une nouvelle version. Vous souhaiterez peut-être vous abonner aux notifications des nouvelles versions dans le dépôt 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 au niveau 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 et 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 dépôts publics, utilisez un jeton d’accès avec la portée public_repo.
  • Pour les organisations, utilisez un jeton d’accès avec 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 se connectent à votre instance GitHub Enterprise Server pour recevoir des affectations de tâches et télécharger les nouvelles versions de l'application exécutrice.

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.

Exigences en matière de communication avec votre instance GitHub Enterprise Server

  • L'application auto-hébergée doit être exécutée sur la machine hôte pour accepter et 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 de se connecter à GitHub.com, à moins que vous ayez 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, 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). Un exemple des exigences pour les exécuteurs de tâches auto-hébergés utilisant des noms de domaine génériques est présenté ci-dessous. 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.