Votre tâche iOS reste en attente, ou le Runner macOS apparaît hors ligne dans GitHub Actions.
Cette semaine, commencez par distinguer le Runner hors ligne, le Runner en ligne qui ne reçoit pas de tâche et l’échec après le démarrage du travail ; vérifiez ensuite l’hôte, le réseau, launchd, les étiquettes et les journaux. Ne remplacez pas le Mac avant d’avoir écarté une erreur de routage ou de configuration.
Ce guide s’adresse aux personnes qui maintiennent un Runner macOS auto-hébergé et doivent isoler un problème de service ou de connectivité.
Il est aussi conçu pour les équipes iOS dont les tâches s’accumulent et pour les responsables qui évaluent la fiabilité de leur nœud de compilation.
Runner macOS de GitHub Actions hors ligne ou tâche en attente : deux symptômes à séparer
Un statut « hors ligne » n’indique pas la même panne qu’une tâche en attente. Avant de redémarrer quoi que ce soit, notez le statut affiché dans les paramètres du dépôt ou de l’organisation, l’étape à laquelle le travail est bloqué et la dernière exécution réussie. Cette trace simple vous évite d’attribuer à l’hôte un problème qui vient en réalité des étiquettes, des autorisations ou du travail lui-même.
Pour établir le bon point de départ, répartissez le diagnostic en trois branches : le Runner est hors ligne ; il est disponible, mais aucune tâche ne lui correspond ; ou il a accepté le travail et l’échec survient pendant l’exécution. Cette séparation reprend les états et les points d’entrée décrits dans la documentation de dépannage des Runner macOS. Une compilation échouée après son lancement n’est donc pas, à elle seule, la preuve que le Runner est déconnecté.
Consignez l’heure de l’incident et l’identifiant de l’exécution, puis comparez-les aux journaux. Évitez d’effacer ou de réenregistrer un Runner dès le premier incident : vous pourriez perdre des éléments utiles, tout en laissant intacte la cause, par exemple un Mac suspendu ou une configuration de tâche incompatible.
| Ce que vous observez | Ce que cela indique d’abord | Première vérification utile |
|---|---|---|
| Le Runner est affiché hors ligne | L’hôte, le processus ou la communication avec GitHub peut être interrompu | Vérifier que le Mac est accessible, puis contrôler le service et la connectivité |
| Le Runner est en ligne, mais la tâche attend | Aucun Runner disponible ne satisfait nécessairement les critères de routage | Comparer les étiquettes demandées, celles du Runner et les permissions de son groupe |
| Le travail a commencé, puis échoue | Le Runner a accepté la tâche ; le problème peut venir de l’environnement ou du script | Aligner le journal du travail sur les journaux de diagnostic du Runner |
Ces correspondances sont des pistes, pas un diagnostic automatique. Les règles de routage dépendent des étiquettes et des groupes configurés pour le dépôt ou l’organisation : vérifiez la configuration effective, plutôt que de vous fier à une ancienne copie de votre fichier de workflow.
Le Runner auto-hébergé macOS est-il réellement hors ligne ?
Commencez par confirmer que le Mac est allumé, qu’il n’est pas suspendu et que vous pouvez l’atteindre par le canal d’administration habituel. Vérifiez ensuite si le processus Runner existe et si son service démarre correctement. Un Mac accessible en SSH peut encore héberger un Runner arrêté ; inversement, un processus local actif ne prouve pas que l’hôte communique correctement avec GitHub.
Dans l’interface d’administration, observez aussi si le statut évolue après le redémarrage du service. Si l’état reste « hors ligne », enregistrez l’heure à laquelle la tentative de connexion a eu lieu et passez à l’examen du réseau. La documentation officielle de référence sur les Runner auto-hébergés décrit le rôle du Runner dans l’attribution du travail ; la page de dépannage macOS présente les contrôles liés à son état.
Ne concluez pas qu’un échec d’authentification ou de réseau se corrige en désactivant la vérification TLS. Ce changement affaiblit la sécurité de la connexion sans prouver que le problème est résolu. Recherchez plutôt la cause dans la configuration du proxy ou du pare-feu, la résolution DNS, l’heure système et les journaux produits au moment précis de l’échec.
Quels journaux consulter si la connexion réseau échoue ?
Exécutez la vérification de connectivité prévue par la documentation officielle correspondant à votre installation et conservez sa sortie. Les restrictions de sortie réseau, les règles de proxy ou une résolution DNS défaillante peuvent empêcher le Runner de joindre les services nécessaires, même si les autres usages du Mac semblent fonctionner. Vérifiez les règles réellement appliquées à l’hôte : une connexion SSH opérationnelle ne valide pas automatiquement les connexions sortantes utilisées par GitHub Actions.
Quand la vérification signale un échec, comparez-le aux diagnostics du Runner. Dans le répertoire d’installation, les journaux du sous-répertoire _diag aident à repérer les erreurs de communication et à aligner leur heure avec le statut observé. Pour une exécution qui a démarré, consultez aussi le journal du travail dans l’interface : la documentation sur les journaux d’exécution explique où les retrouver. Ces deux sources ne répondent pas à la même question : l’une éclaire le fonctionnement du Runner, l’autre le déroulement des étapes du workflow.
Si les journaux ne sont pas assez détaillés, activez temporairement la journalisation de débogage en suivant la procédure décrite dans la documentation officielle sur les journaux de débogage. Répétez le diagnostic pendant la fenêtre où le problème se produit, puis désactivez le niveau de journalisation supplémentaire lorsque les informations ne sont plus nécessaires. N’exposez pas de jetons, de secrets ou de données de projet en partageant des extraits.
Runner en ligne ou travail en attente : vérifier d’abord le routage
Un Runner en ligne n’est pas nécessairement éligible à toutes les tâches. Le workflow peut demander un ensemble d’étiquettes que ce Runner ne possède pas, ou cibler un groupe qui ne peut pas accéder au dépôt. GitHub attribue les tâches selon les critères de routage configurés ; le statut « en ligne » indique donc une disponibilité de connexion, pas une compatibilité universelle.
Regardez la propriété runs-on du travail concerné, puis comparez-la aux étiquettes affichées pour le Runner. Les étiquettes par défaut documentées comprennent self-hosted, un système d’exploitation tel que macOS et une architecture telle que ARM64 ; utilisez les valeurs réelles de votre environnement et vérifiez les correspondances dans la documentation des étiquettes et du routage. Une différence de casse, une étiquette personnalisée absente ou une hypothèse erronée sur l’architecture suffit à rendre une tâche incompatible.
| Élément à comparer | Question de diagnostic | Conséquence possible |
|---|---|---|
runs-on dans le workflow |
Toutes les étiquettes demandées sont-elles attribuées au Runner ciblé ? | Une étiquette manquante empêche l’attribution à ce Runner |
| Groupe du Runner | Le travail vise-t-il le groupe auquel appartient le Runner ? | Un groupe différent peut exclure le nœud du routage |
| Accès au dépôt | Le groupe est-il autorisé à servir ce dépôt ou cette organisation ? | Un Runner en ligne peut rester indisponible pour ce travail |
| Architecture et système | Les critères demandés correspondent-ils à l’environnement réel ? | Une valeur incorrecte peut laisser la tâche en attente |
Les restrictions d’accès ne se déduisent pas toujours de la liste des machines disponibles. Contrôlez les règles du groupe et les dépôts autorisés à l’utiliser, comme l’explique la documentation sur la gestion de l’accès aux groupes de Runner. Si plusieurs Runner partagent une étiquette, vérifiez aussi que ceux qui sont en ligne peuvent réellement accepter le travail et que les limites ou autorisations du groupe ne l’excluent pas.
Pour tester une correction, modifiez uniquement le critère que vous avez identifié, puis relancez une tâche de vérification adaptée. Si vous changez simultanément le groupe, les étiquettes et l’hôte, vous ne saurez pas quelle modification a corrigé le routage. Une erreur de YAML ou d’étiquette se résout dans le workflow ou dans la configuration du Runner ; migrer vers une autre machine ne corrige pas ce type de défaut.
Comment vérifier le service launchd du Runner macOS ?
Un Runner lancé manuellement dans un terminal et un Runner configuré comme service ne suivent pas le même chemin de démarrage. Une session interactive qui fonctionne ne démontre pas que le service launchd redémarrera correctement après une fermeture de session ou un redémarrage de l’hôte. Pour établir le fonctionnement en continu, examinez le service réellement installé et son compte d’exécution.
Depuis le répertoire d’installation du Runner, consultez l’état avec le script de service fourni, lorsque celui-ci est disponible dans votre installation. La procédure officielle pour configurer l’application Runner sur macOS décrit les opérations de service et les contrôles associés : suivez-la plutôt que de réutiliser une commande issue d’une autre version ou d’un autre mode d’installation. Vérifiez également le compte configuré, les permissions sur le répertoire de travail et l’accès aux outils de compilation dont le service a besoin.
Comparez ensuite l’heure de la dernière tentative de démarrage avec les journaux système et ceux du Runner. Si l’exécution interactive réussit, mais que le service échoue, cherchez un écart de variables d’environnement, de chemin d’accès, de droits ou de session utilisateur. Les outils installés dans le profil d’un compte ne sont pas nécessairement visibles de la même façon pour un service démarré sous un autre contexte.
Ne déclarez pas le problème réglé après un démarrage manuel réussi. Relancez le service selon la procédure officielle, vérifiez son état depuis le contexte attendu et confirmez qu’il reste joignable après le cycle de redémarrage pertinent pour votre exploitation. La documentation de configuration du service Runner sur macOS est la référence à consulter pour les étapes exactes, car les commandes disponibles peuvent dépendre de l’installation en place.
Travail accepté ou Runner déconnecté : lire la phase exacte de l’échec
Lorsque la tâche apparaît comme démarrée, examinez d’abord l’étape précise qui échoue dans le journal du workflow. Une erreur pendant la récupération des dépendances, la signature, la compilation ou un script de projet ne signifie pas que le Runner n’a pas pris le travail : au contraire, il a pu le recevoir correctement avant que l’environnement ne rencontre un problème.
Alignez l’heure de l’échec avec les journaux de diagnostic du Runner. Si l’erreur se produit avant que les étapes du workflow ne s’exécutent, cherchez du côté de la prise en charge du travail, de la communication ou du service. Si elle survient pendant une commande du projet, examinez la commande, les variables nécessaires, les droits d’accès et la disponibilité de ses dépendances. Gardez le message d’erreur complet : une ligne isolée peut masquer l’étape qui a réellement échoué.
Pour les outils et versions, comparez l’état réel du Mac à celui attendu par votre projet. Vérifiez le système, l’architecture, les outils installés, les certificats et les autorisations dont le travail dépend. N’attribuez pas l’incident à une génération de processeur ou à un modèle de Mac sans élément dans les journaux : le résultat d’une compilation varie aussi selon le projet, les dépendances et les scripts exécutés.
Liste de vérification avant de changer d’hôte
Utilisez cette liste avant de modifier l’infrastructure. Cochez un point seulement après avoir vérifié le résultat dans l’interface, la configuration ou un journal correspondant.
- [ ] J’ai relevé le statut exact du Runner et l’étape à laquelle la tâche s’arrête.
- [ ] J’ai confirmé que le Mac est accessible et qu’il n’est pas suspendu ou arrêté.
- [ ] J’ai vérifié que le processus ou le service Runner est actif dans le contexte attendu.
- [ ] J’ai comparé
runs-on, les étiquettes attribuées et le groupe visé. - [ ] J’ai confirmé que ce groupe est autorisé à servir le dépôt concerné.
- [ ] J’ai vérifié la connectivité sortante à l’aide de la procédure officielle, sans désactiver TLS.
- [ ] J’ai rapproché l’heure de l’incident des journaux du Runner et du workflow.
- [ ] J’ai distingué une défaillance du Runner d’une erreur de script, de dépendance ou de droits.
- [ ] J’ai retesté la correction isolément avant d’envisager une migration.
Si toutes les vérifications de configuration passent, mais que l’hôte reste régulièrement indisponible, vous avez un motif concret pour évaluer l’infrastructure. Si une seule vérification de routage échoue, corrigez plutôt cette configuration et relancez le test avant de comparer des solutions d’hébergement.
Réparer le nœud ou changer d’exploitation : une décision par cause
Le choix ne se résume pas à « Runner auto-hébergé ou Mac distant ». Il dépend de la cause identifiée, du temps que votre équipe peut consacrer à l’exploitation et de la nécessité de disposer d’un environnement macOS en continu. La comparaison ci-dessous est qualitative : elle décrit des situations de maintenance, sans prétendre mesurer les performances d’une machine particulière.
| Option | Adaptée lorsque… | Limite à prendre en compte | Appréciation pour ce symptôme |
|---|---|---|---|
| Corriger les étiquettes ou le groupe | Le Runner est en ligne, mais le travail ne correspond pas aux critères de routage | Ne résout pas une panne d’hôte ou de réseau | Prioritaire si le routage est en cause |
| Stabiliser le Mac existant | Les journaux indiquent une suspension, un service mal configuré ou un incident réseau local | Votre équipe reste responsable de l’hôte et de son suivi | Pertinent si l’accès et la maintenance sont maîtrisés |
| Utiliser un Mac distant en continu | L’indisponibilité de l’hôte ou la charge de maintenance est le problème établi | Ne corrige pas une erreur YAML, une étiquette incorrecte ou un script défaillant | À évaluer si l’exploitation du Mac local n’est pas fiable |
| Revoir le processus de compilation | L’échec se produit dans les étapes du projet après l’acceptation du travail | Demande d’analyser l’environnement et les dépendances du projet | Prioritaire si les journaux désignent le build plutôt que le Runner |
Un score de pertinence peut vous aider à comparer les options sans le confondre avec un indice de performance mesuré. Pour un problème d’étiquettes, la correction de configuration a une pertinence élevée et le changement d’hôte une pertinence faible. Pour un Mac qui s’arrête ou ne peut pas être maintenu disponible, la stabilisation de l’hôte ou l’évaluation d’un Mac distant devient plus pertinente. Pour un script qui échoue après le démarrage, concentrez vos efforts sur le workflow et l’environnement du projet avant toute migration.
Si vous devez simplement confirmer vos critères de routage, comparez d’abord la configuration actuelle et les journaux : une migration ajoute des changements sans réparer une étiquette manquante. En revanche, si vous avez établi que le Mac n’est pas joignable de façon fiable ou que l’équipe ne peut pas maintenir son service, vous pouvez examiner un environnement Mac distant comme solution d’exploitation. Pour confronter cette option à vos contraintes de durée et de budget, consultez aussi les formules disponibles avant de décider.
Quand le Mac distant apporte une réponse pertinente
Un Mac distant peut être utile si vos journaux montrent que le nœud actuel est régulièrement indisponible, si son maintien mobilise trop de temps d’exploitation ou si votre équipe doit disposer d’un environnement macOS accessible sans dépendre d’un poste local qui s’éteint. Il ne dispense cependant pas de vérifier la connectivité, le compte de service, les permissions, les étiquettes et la configuration du workflow. Le même défaut de routage ou le même script invalide peut persister sur un autre hôte.
Avant de transférer un Runner, vérifiez que votre mode d’accès et votre politique de sécurité conviennent au dépôt et aux secrets utilisés par la chaîne de compilation. Prévoyez une période de validation pendant laquelle vous comparez les journaux et les résultats de compilation, sans supprimer le nœud existant avant d’avoir confirmé que le nouveau fonctionnement répond à vos besoins. Les détails d’accès et de disponibilité doivent être vérifiés dans les informations du service que vous envisagez ; ne les déduisez pas de la seule mention « distant ».
Le Mac local reste souvent préférable si vous avez besoin d’interfaces physiques, d’un accès direct à des périphériques ou d’un environnement stable que votre équipe sait déjà administrer. Un autre hôte ne sera pas automatiquement plus simple si votre problème réside dans le workflow, les secrets ou la configuration de launchd.
En revanche, lorsque la panne est bien liée à la disponibilité du Mac ou à la difficulté de maintenir le service, continuer à dépendre d’un poste local peut entraîner des redémarrages manuels, des périodes sans Runner et du temps consacré à diagnostiquer l’hôte au lieu des compilations. Un Mac distant loué auprès de VPSPull peut alors vous offrir un environnement macOS accessible pour exploiter le Runner, sous réserve de vérifier que ses modalités d’accès conviennent à votre projet. Évaluez cette option à partir de vos journaux et de vos besoins réels ; ne l’utilisez pas comme substitut à la correction d’une erreur de routage ou de configuration.
Hébergez votre runner CI sur un Mac dédié
Avec VPSPull, choisissez un Mac Apple Silicon physique dédié pour exécuter vos tâches de compilation et de test dans un environnement macOS complet.
