Stabilisation des runners GitHub Actions auto-hébergés sous Windows et WSL2

Telluric a publié Joggo, une boîte à outils open source conçue pour stabiliser les runners GitHub Actions auto-hébergés sur les machines Windows utilisant WSL2. Publié en novembre 2026, le projet traite des problèmes spécifiques d'instabilité qui surviennent lors de l'exécution de builds de production sur du matériel de bureau standard plutôt que sur une infrastructure cloud dédiée. Il fournit des scripts concrets et une documentation pour gérer les pannes telles que la dérive d'horloge, l'épuisement de la mémoire et les timeouts réseau.

Ce qui s'est passé

Le projet est né d'un déploiement réel où un seul PC Windows doté de 16 Go de RAM a servi de runner CI/CD pendant plusieurs mois. À partir de juin 2026, le système est passé d'un runner unique à une configuration conteneurisée avec plusieurs slots d'ici octobre. Durant cette période, l'opérateur a rencontré des problèmes récurrents tels que les redémarrages dus aux mises à jour Windows tuant les jobs, les démons Docker devenant non réactifs et la mémoire disponible chutant à des niveaux critiques. Au lieu de masquer ces difficultés, les développeurs ont documenté chaque mode de défaillance, les mesures prises et les correctifs spécifiques qui ont fonctionné.

Joggo n'est pas un opérateur Kubernetes complexe ni un gestionnaire de flotte autoscaling. Il s'agit d'un ensemble de scripts et de fichiers de configuration destinés aux petites équipes ou aux développeurs individuels souhaitant exécuter des builds sur du matériel local inactif. Le code est abondamment commenté, chaque fichier expliquant la panne qui a nécessité sa création. La documentation met l'accent sur le dépannage pratique, offrant une « page la plus utile » sur la pression mémoire, détaillant comment les émulateurs de terminal et autres processus en arrière-plan peuvent affamer les conteneurs de build en ressources.

Détails clés

• Environnement cible : L'outil ne prend en charge que Windows 10 (version 2004+) ou Windows 11 avec WSL2 activé. Il ne prend pas en charge Linux natif ni les machines virtuelles hors de cette configuration spécifique.
• Résolutions des pannes : Il inclut des correctifs pour la perte de paquets DNS causant des timeouts, la dérive d'horloge WSL2 invalidant les tokens OAuth, et les blocages d'écouteurs laissant les runners apparaissant actifs mais non réactifs.
• Gestion de la mémoire : Un garde-fou intégré échantillonne l'utilisation de la mémoire toutes les cinq minutes. Si la mémoire libre tombe sous 15 % de la RAM totale, il met en pause les nouveaux slots de job ; si elle tombe sous 7,5 %, il peut redémarrer la VM si aucun job n'est en cours.
• Modèle de sécurité : Le runner exécute du code provenant de dépôts autorisés sur le matériel local. Le projet conseille strictement de ne pas autoriser les dépôts publics ou les pull requests de forks à déclencher des workflows sur ces runners.
• Installation : La configuration est gérée via des scripts PowerShell pouvant s'exécuter en mode assistant interactif ou en mode non interactif pour les agents. Elle prend en charge les portées compte personnel et organisation.
• Compromis coût : Bien qu'il élimine les minutes facturables GitHub Actions pour les dépôts privés, il introduit des coûts liés à l'électricité, à l'usure du matériel et à des temps de démarrage de job plus lents dus aux reconstructions de conteneurs lors de la passation.

Contexte

Les runners auto-hébergés permettent aux organisations d'exécuter des workflows GitHub Actions sur leur propre infrastructure. Cela est souvent fait pour réduire les coûts associés aux minutes facturables, en particulier pour les runners Windows et macOS qui sont facturés plus cher que leurs équivalents Linux dans le modèle de facturation de GitHub. Cependant, déplacer les charges de travail CI/CD vers des machines locales introduit des défis opérationnels. Les fournisseurs cloud gèrent automatiquement la fiabilité du matériel, la stabilité du réseau et l'isolation de sécurité. Lors de l'hébergement local, les ingénieurs doivent gérer manuellement les coupures de courant, les mises à jour du système d'exploitation et la contention des ressources.

WSL2 (Windows Subsystem for Linux 2) permet aux binaires Linux de s'exécuter nativement sur Windows. Bien que puissant, il présente des particularités connues, telles que des problèmes de synchronisation d'horloge lorsque la machine hôte se met en veille et des comportements de gestion de la mémoire différents des noyaux Linux standards. Joggo adresse ces points d'intersection spécifiques, fournissant un pont entre l'environnement hôte Windows et les conteneurs de runner basés sur Linux.

Pourquoi c'est important

Pour les équipes développant leur propre logiciel, le coût du CI/CD cloud peut devenir significatif à mesure que la complexité du projet augmente. Déplacer les builds vers du matériel local peut éliminer la facturation à la minute, mais seulement si l'environnement local est fiable. Des runners instables entraînent des retards de déploiement, des développeurs frustrés et des risques potentiels de sécurité s'ils ne sont pas correctement isolés. Joggo fournit un cadre testé pour rendre cette transition viable sans nécessiter une équipe DevOps dédiée pour gérer une infrastructure personnalisée.

La documentation détaillée sur les modes de défaillance est particulièrement précieuse pour les responsables IT et les administrateurs système. Au lieu de deviner pourquoi un build a échoué, ils peuvent se référer à des critères diagnostiques spécifiques fournis par le projet. Par exemple, distinguer un job qui n'a jamais démarré d'un job ayant échoué en cours d'exécution nécessite de vérifier des champs de payload spécifiques. Ce niveau de clarté opérationnelle réduit le temps moyen de récupération et aide les équipes à maintenir la confiance dans leur configuration auto-hébergée.

Ce que vous pouvez faire

• Auditez vos coûts CI actuels : Vérifiez vos paramètres de facturation GitHub pour déterminer si votre dépense en minutes Windows ou macOS justifie l'effort de mise en place de runners auto-hébergés.
• Examinez les limites de sécurité : Assurez-vous que tout runner auto-hébergé est configuré pour accepter les jobs uniquement depuis des dépôts privés de confiance. N'activez jamais l'accès aux dépôts publics sur du matériel local.
• Testez les seuils de mémoire : Si vous prévoyez d'utiliser Joggo, exécutez les vérifications préalables sur votre machine cible pour vérifier que votre allocation de RAM répond aux exigences minimales pour le nombre de slots de runner souhaité.
• Mettez en œuvre la surveillance : Utilisez les outils fournis pour suivre le statut des runners et l'utilisation de la mémoire. Configurez des alertes pour l'activation du garde-fou mémoire afin d'enquêter sur les processus gourmands en ressources sur la machine hôte.
• Lisez la documentation de récupération : Familiarisez-vous avec le tableau de triage dans la documentation de récupération. Connaître la différence entre une horloge figée et un écouteur bloqué vous fera gagner des heures de débogage.
• Commencez petit : Commencez avec un seul slot de runner sur un projet non critique pour valider la configuration avant de migrer l'intégralité de votre pipeline CI vers du matériel local.