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

Consultez des informations concernant la configuration ainsi que l’exploitation des runners auto-hébergés.

Dans cet article

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, Windows (actuellement en préversion publique).
  • 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.

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

Les runners hébergés par GitHub effectuent intrinsèquement une mise à l’échelle automatique en fonction de vos besoins. Les runners hébergés par GitHub peuvent constituer une alternative économique et nécessitant peu de maintenance au développement ou à la mise en œuvre de solutions de mise à l’échelle automatique. Pour plus d’informations, consultez « Exécuteurs hébergés par GitHub ».

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.

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 à GitHub 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 runner se met automatiquement à jour lorsqu’une tâche est attribuée au runner, ou dans la semaine suivant sa publication si aucune tâche n’a été attribuée au runner.

Conditions requises pour la communication avec GitHub

  • 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.
  • La machine hôte doit disposer d'un accès réseau approprié avec une vitesse de téléchargement et de chargement d'au moins 70 kilobits par seconde.
  • L’ordinateur hôte doit pouvoir établir des connexions HTTPS sortantes sur le port 443.
  • Selon la fonction des flux de travail attribués à votre exécuteur auto-hébergé, l’ordinateur hôte doit être en mesure de communiquer avec les GitHub domaines répertoriés ci-dessous.

Domaines accessibles par fonction

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.

Remarque

Si vous utilisez GitHub Enterprise Cloud avec résidence des données, vos runners doivent communiquer avec des noms d’hôte supplémentaires, en plus de ceux indiqués ci-dessous. Pour connaître la configuration réseau requise, consultez Détails réseau pour GHE.com.

Requis pour les opérations essentielles :

Shell
github.com
api.github.com
*.actions.githubusercontent.com

Requis pour télécharger les actions :

Shell
codeload.github.com

Requis pour charger/télécharger des résumés de projets, des journaux d'activité, des artefacts de workflow et des caches :

Shell
results-receiver.actions.githubusercontent.com
*.blob.core.windows.net

Nécessaire pour les mises à jour de version de l’agent d’exécution :

Shell
objects.githubusercontent.com
objects-origin.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com

Requis pour récupérer les jetons OIDC :

Shell
*.actions.githubusercontent.com

Nécessaire pour télécharger ou publier des packages ou des conteneurs sur GitHub packages :

Shell
*.pkg.github.com
pkg-containers.githubusercontent.com
ghcr.io

Nécessaire pour Stockage des fichiers volumineux Git

Shell
github-cloud.githubusercontent.com
github-cloud.s3.amazonaws.com

Requis pour les tâches de Dependabot updates

Shell
dependabot-actions.githubapp.com

Nécessaire pour télécharger les fichiers de la version :

Shell
release-assets.githubusercontent.com

Nécessaire pour le réseau virtuel :

Shell
api.snapcraft.io

En outre, votre workflow peut nécessiter l’accès à d’autres ressources réseau.

Si vous utilisez une liste verte d’adresses IP pour votre compte d’organisation ou d’entreprise GitHub, vous devez ajouter l’adresse IP de votre runner auto-hébergé à cette liste verte. Consultez La gestion des adresses IP autorisées pour votre organisation ou l’application de stratégies pour les paramètres de sécurité de votre entreprise