Que faire si le Runner Mac auto-hébergé GitHub Actions est hors ligne après redémarrage ? Guide de dépannage 2026

Un état « Offline » dans GitHub ne dit pas, à lui seul, si le Mac a redémarré correctement. Nous commençons donc par comparer l’état affiché dans l’interface à un test d’accès indépendant et aux traces de l’opération de redémarrage.

Cochez les points suivants avant de modifier la configuration :

• [ ] L’hôte répond par le canal d’administration habituel : partage d’écran, VNC, SSH ou console disponible dans votre environnement.
• [ ] Les journaux ou l’outil de gestion du parc confirment que le Mac a terminé son démarrage, et non qu’il est toujours arrêté ou bloqué.
• [ ] Le compte utilisé pour l’administration correspond bien à la machine et à l’environnement concernés.
• [ ] L’heure du dernier redémarrage et les événements consignés par l’équipe concordent avec l’état observé.

Si le Mac ne répond pas, ne commencez pas par réinstaller le Runner. Une commande de configuration ne peut pas réparer un hôte qui n’a pas terminé son démarrage, qui n’a plus de réseau ou qui n’est pas alimenté. Il faut d’abord rétablir l’accès à la machine, puis confirmer qu’elle est stable avant d’intervenir sur l’application.

Si le Mac répond, mais que GitHub indique toujours « Offline », séparez les symptômes. L’accès à distance prouve que l’hôte est joignable depuis le poste d’administration ; il ne prouve pas que le processus Runner est actif, ni que ce processus peut établir ses connexions sortantes vers GitHub. Cette distinction évite de confondre accès opérateur et disponibilité de la CI.

Après avoir confirmé que le Mac est accessible, nous vérifions si le service Runner a été installé et s’il s’exécute dans le contexte attendu. GitHub fournit un script de gestion du service dans le répertoire de l’application ; les commandes disponibles et leur configuration sont décrites dans la documentation de configuration du Runner macOS.

Depuis le répertoire du Runner, consultez l’état avec le script de service fourni. Comparez ensuite ce résultat à l’état affiché dans GitHub. Si le service est absent, arrêté ou en erreur, notez le message avant de tenter un redémarrage. Un simple redémarrage répété sans collecte de traces peut masquer la cause initiale.

La question importante est celle du contexte de lancement. Un LaunchAgent s’exécute dans le contexte d’un utilisateur ; un LaunchDaemon relève du contexte système. Les deux ne sont pas interchangeables : un processus lancé seulement dans une session utilisateur peut ne pas repartir comme attendu lorsqu’aucun utilisateur n’est connecté. La documentation Apple sur Service Management décrit ces modèles de gestion des services.

Pour éviter une remise en service fragile, vérifiez les éléments suivants :

• [ ] Le service correspond à l’installation actuelle du Runner, pas à un ancien répertoire.
• [ ] Le fichier de service et le nom de l’instance concordent avec l’enregistrement visible dans GitHub.
• [ ] Le contexte launchd permet le fonctionnement attendu sans dépendre d’une ouverture de session interactive.
• [ ] Le script de service retourne un état interprétable et les journaux ne signalent pas une erreur de lancement.
• [ ] Le redémarrage manuel du service ne masque pas une erreur de permissions ou de chemin d’accès.

Un processus lancé après ouverture de session ne prouve pas que le service démarrera au prochain redémarrage. Vérifiez le contexte launchd et l’état du service dans la situation réelle d’exploitation, notamment lorsqu’aucun utilisateur n’est connecté.

Cette vérification est particulièrement utile pour les machines administrées à distance. Si le Runner dépend d’une session graphique, d’un trousseau ou d’un environnement propre à l’utilisateur, consignez cette dépendance et traitez-la comme une condition d’exploitation. Ne la confondez pas avec une panne de connectivité GitHub.

Un navigateur qui charge une page ne valide pas les accès du service Runner. Celui-ci peut utiliser un autre contexte, un autre proxy ou d’autres paramètres d’environnement. Nous examinons donc le chemin réseau réellement emprunté par le processus, plutôt que de conclure à partir d’un test Internet général.

Suivez une séquence de diagnostic cohérente :

• [ ] Vérifiez la résolution DNS et les erreurs de connexion observées par le Runner.
• [ ] Confirmez que les règles réseau autorisent les connexions sortantes nécessaires depuis le Mac.
• [ ] Si un proxy est imposé, vérifiez sa configuration pour l’application Runner, et pas seulement pour le navigateur ou la session de l’administrateur. GitHub précise les modalités de proxy dans son guide consacré aux serveurs mandataires pour Runner auto-hébergés.
• [ ] Contrôlez les erreurs TLS, les certificats inspectés par un équipement intermédiaire et les changements récents de règles réseau.
• [ ] Utilisez le contrôle de connectivité et les journaux de diagnostic indiqués dans le guide de dépannage GitHub.

Si le Runner est joignable mais que les connexions à GitHub échouent, conservez le message d’erreur exact et l’heure de l’essai. Une résolution DNS qui échoue, un refus du proxy et un problème de certificat ne se corrigent pas de la même manière. La trace permet aussi de transmettre au réseau ou à la sécurité un élément exploitable, plutôt qu’un simple constat d’indisponibilité.

Pour approfondir l’origine d’un échec, activez les journaux de diagnostic selon la procédure GitHub. La documentation prévoit deux variables de débogage : ACTIONS_RUNNER_DEBUG et ACTIONS_STEP_DEBUG (guide GitHub sur les journaux de débogage). Utilisez-les pour une investigation contrôlée, puis retirez la configuration de diagnostic lorsqu’elle n’est plus nécessaire.

Ne désactivez pas la validation TLS pour faire passer un test. Cela transforme un défaut de configuration en risque de sécurité et rend le résultat difficile à interpréter. Corrigez plutôt la chaîne de certificats, la configuration du proxy ou la règle réseau identifiée, puis refaites le contrôle.

Un Runner peut être affiché comme « Online » sans être sélectionné par le travail attendu. GitHub choisit un Runner selon les critères de runs-on, les labels disponibles et les autorisations associées au groupe. La documentation explique cette sélection dans le guide sur le choix du Runner pour un travail.

Pour contrôler le routage, comparez la configuration du workflow à celle du Runner :

• [ ] Les labels demandés dans runs-on correspondent aux labels affichés pour le Runner.
• [ ] Les labels nécessaires sont bien attribués ; GitHub documente les labels des Runner auto-hébergés.
• [ ] Le Runner appartient au groupe attendu par la configuration.
• [ ] Le groupe autorise l’accès au dépôt concerné ; vérifiez les règles de gestion des accès aux groupes de Runner.
• [ ] Le travail en attente n’exige pas un label ou une permission qui n’existe pas sur ce Runner.

Les Runner GitHub disposent de trois labels par défaut, correspondant à self-hosted, au système d’exploitation et à l’architecture ; vérifiez les valeurs réellement affichées plutôt que de supposer qu’elles satisfont votre workflow (documentation des labels). Une tâche ciblant un label personnalisé ne sera pas dirigée vers un Runner qui ne le possède pas, même si son état est « Online ».

Une tâche en attente n’est donc pas automatiquement la preuve d’une panne du service. Elle peut révéler une divergence de label, une restriction du groupe ou une autorisation insuffisante. Corrigez le critère de routage ou l’accès concerné ; ne réenregistrez pas une machine saine uniquement parce qu’elle ne reçoit pas un travail auquel elle ne correspond pas aux critères de sélection.

Lorsque l’hôte est accessible, le service tourne et la connectivité fonctionne, comparez les enregistrements de Runner présents dans GitHub aux fichiers et services du Mac. Une ancienne entrée peut donner l’impression que l’instance actuelle est enregistrée alors que le processus lancé utilise une autre configuration. À l’inverse, plusieurs services associés à des répertoires différents peuvent brouiller le diagnostic.

Relevez le nom de Runner affiché, le répertoire de l’application, l’état du service et les labels. Recherchez ensuite les divergences : nom différent, ancien service encore chargé, répertoire déplacé ou configuration de Runner qui ne correspond pas à l’enregistrement actuel. Conservez les éléments avant d’en retirer un ; les supprimer trop tôt rend plus difficile l’identification de l’instance qui répond réellement.

La suppression puis la réinscription ne sont pertinentes que si les preuves indiquent un problème d’enregistrement ou une configuration devenue inutilisable. Avant cette opération, vérifiez les permissions de l’équipe, le groupe cible, les labels et la procédure d’inscription autorisée. Si les preuves pointent plutôt vers un service arrêté ou un proxy mal configuré, réenregistrer le Runner ne traite pas la cause.

Cette discipline évite aussi de créer une configuration concurrente lors d’une intervention à distance. Si une autre personne travaille déjà sur le Mac, coordonnez les changements : deux corrections simultanées peuvent déplacer le service, modifier les labels et brouiller l’état que l’équipe essaie de rétablir.

Pourquoi le Runner Mac peut-il apparaître hors ligne après un redémarrage ?
GitHub associe cet état à plusieurs causes possibles : l’hôte peut être inaccessible, l’application Runner peut ne pas fonctionner, ou le processus peut ne pas communiquer avec GitHub. Vérifiez l’accès au Mac, puis le service et les journaux réseau. Un enregistrement présent dans l’interface ne prouve pas que le processus correspondant tourne.

Comment confirmer que le service Runner macOS a démarré sans session utilisateur ?
Consultez l’état avec le script de service fourni dans le répertoire du Runner, puis vérifiez le contexte launchd associé. Un LaunchAgent dépend d’une session utilisateur, tandis qu’un LaunchDaemon relève du contexte système. Si le processus n’apparaît qu’après connexion d’un utilisateur, contrôlez le modèle de lancement plutôt que de conclure à une erreur d’enregistrement.

Que vérifier si le processus Runner tourne, mais que GitHub l’affiche toujours hors ligne ?
Examinez la résolution DNS, les règles de sortie, le proxy utilisé par le Runner et les erreurs TLS. Un accès Internet depuis un navigateur ne garantit pas que le service dispose du même chemin réseau. Consultez le contrôle de connectivité et les journaux de diagnostic ; ne contournez pas le contrôle TLS pour faire disparaître l’erreur.

Comment savoir si un Runner en ligne peut prendre en charge les travaux attendus ?
Comparez les labels de runs-on à ceux du Runner et vérifiez l’accès du groupe au dépôt. Exécutez ensuite une tâche de validation dépourvue de secrets de signature de production. Le résultat doit confirmer la prise en charge du travail, l’accès à l’espace de travail, l’exécution des outils nécessaires et la remontée des résultats.

Nous n’autorisons la reprise des travaux de production qu’après vérification de la chaîne complète. Utilisez ces conditions comme décision d’équipe :

• Si le Mac ne répond pas, alors rétablissez d’abord l’accès à l’hôte et confirmez son démarrage ; sinon, passez à l’état du service.
• Si le service est arrêté ou rattaché au mauvais contexte launchd, alors corrigez le service avant de tester le réseau ; sinon, examinez les connexions du processus Runner.
• Si le Runner ne communique pas avec GitHub, alors traitez le DNS, le proxy, les règles de sortie ou TLS à partir des journaux ; sinon, passez au routage.
• Si le Runner est en ligne mais qu’aucune tâche attendue ne lui correspond, alors vérifiez runs-on, les labels et les autorisations du groupe ; sinon, cherchez une divergence d’enregistrement ou un défaut propre au workflow.
• Si une tâche représentative échoue, alors gardez la production en attente et corrigez le point d’échec ; si elle réussit et que les critères de publication sont satisfaits, alors autorisez la reprise selon le processus de l’équipe.

La validation finale doit être une vraie exécution contrôlée, pas seulement une observation de l’état « Online ». Choisissez un travail représentatif qui ne touche ni aux certificats ni aux secrets de signature de production. Vérifiez qu’il est pris en charge, qu’il accède au dépôt et à son espace de travail, qu’il appelle les outils attendus et qu’il transmet son résultat. Selon votre flux, ajoutez un contrôle de compilation ou de test pertinent ; ne déduisez pas qu’une publication iOS est rétablie d’un simple test de connexion.

Consignez l’identifiant du travail, les journaux utiles, le résultat et l’approbation de reprise. Cette trace donne à l’astreinte suivante un point de comparaison et évite de répéter des changements non vérifiés. Elle permet aussi de distinguer un Runner récupéré d’une chaîne de publication réellement autorisée à repartir.

Un Mac exploité en interne donne à l’équipe la maîtrise directe du matériel et des accès physiques, mais impose aussi de gérer le remplacement des composants, les interventions locales et le cycle d’achat. Pour les équipes qui comparent l’achat d’un poste et la capacité distante, la commande d’un Mac mini pour le Japon peut servir de point de comparaison pour un achat matériel, sans préjuger de sa pertinence pour un autre lieu ou des besoins de l’équipe.

Un Runner distant ne supprime pas le besoin de superviser le service, le réseau, les permissions et la reprise. Il déplace une partie de l’exploitation et nécessite de vérifier précisément le mode d’accès et les modalités de livraison avant tout engagement. Si l’incident révèle surtout un manque de capacité d’intervention locale ou une difficulté à fournir un Mac de test temporaire, comparez le coût d’exploitation interne à une ressource Mac distante, sans présumer d’un délai de reprise ou d’un niveau de disponibilité non documenté. Vous pouvez examiner les options de Mac distant proposées par MESHLAUNCH en vérifiant les conditions réellement indiquées. Pour une équipe qui possède déjà un Mac adapté et peut assurer sa maintenance, conserver le nœud interne peut rester le choix le plus simple.

La priorité reste la même quel que soit le mode d’hébergement : séparer l’état de l’hôte, du service, du réseau et du routage, puis faire passer une tâche de validation avant la reprise de production. Si le nœud actuel est difficile à récupérer à distance, documentez d’abord les accès et les critères d’acceptation ; évaluez ensuite si un Mac distant correspond à votre besoin de capacité temporaire ou de continuité d’exploitation.