Les journaux officiels de GitLab citent notamment les signatures killed: 9, exit status 134 et Load failed: 5 parmi les erreurs à examiner sur macOS (documentation GitLab sur l’installation macOS). Si votre Mac répond de nouveau en SSH mais que GitLab affiche encore le Runner hors ligne, ne réinstallez pas immédiatement : localisez d’abord la panne entre l’hôte, la session graphique, le LaunchAgent, l’enregistrement du Runner et le réseau. Pour les tâches de signature ou de simulateur, restaurez la session utilisateur correcte au lieu de remplacer le service par un LaunchDaemon.

Cette procédure est destinée aux développeurs indépendants qui maintiennent un nœud CI distant, aux ingénieurs DevOps gérant plusieurs projets et aux équipes de publication responsables des certificats, du trousseau et des simulateurs. Elle convient aussi aux équipes qui doivent définir un critère d’acceptation pour un nouveau Mac distant avant d’y déplacer des tâches de production.

Commencez par situer la panne, pas par réinstaller

Le cas le plus trompeur est simple : après un redémarrage, la connexion SSH fonctionne, le disque est accessible et le nom d’hôte répond, mais le Runner reste hors ligne dans l’interface GitLab. Cette observation prouve uniquement que macOS a démarré et que le service SSH est atteignable. Elle ne prouve ni que l’utilisateur est connecté graphiquement, ni que le LaunchAgent est chargé, ni que le Runner peut joindre GitLab.

Utilisez cet ordre de prise d’indices :

Couche observée Vérification à effectuer Arrêt du diagnostic si… Suite logique
Hôte macOS Connexion SSH, résolution du nom, stockage et heure système Vous ne pouvez pas ouvrir une session fiable Rétablir l’accès à l’hôte
Session utilisateur Utilisateur actif, session graphique et trousseau disponible La tâche dépend de la signature ou du simulateur et aucune session n’est ouverte Restaurer la session autorisée
Service Processus Runner, fichier plist, domaine utilisateur et journaux Le service n’est pas chargé ou s’arrête immédiatement Examiner le LaunchAgent et ses droits
Connexion Accès sortant, proxy, certificat et heure de dernière connexion Le processus tourne mais GitLab ne le voit pas Corriger réseau ou identité
Exécution CI Étiquettes, règles du projet et droits du compte Le Runner est en ligne mais aucune tâche ne part Corriger l’aiguillage du pipeline

Ne mélangez pas quatre états différents : un LaunchAgent chargé, un processus Runner actif, un Runner enregistré et une tâche réellement exécutable. Un échec à un niveau ne se corrige pas au niveau suivant.

Symptôme dans GitLab ou le terminal Ce que cela démontre réellement Ce que cela ne démontre pas
Le Mac répond en SSH L’hôte et le réseau d’administration fonctionnent Le Runner est lancé
Le processus Runner existe Le binaire est actif à cet instant La connexion au serveur est valide
Le Runner est indiqué en ligne La dernière communication a été acceptée Les étiquettes correspondent à la tâche
La tâche reste en attente Aucun nœud admissible ne l’a prise Le service est nécessairement arrêté
La signature échoue Le trousseau, le certificat ou la session pose problème Le Runner est hors ligne

Pour examiner les commandes disponibles et les chemins de configuration sans deviner une option, référez-vous à la référence officielle des commandes GitLab Runner. Conservez dans vos notes le nom du compte, le chemin du binaire, le chemin de configuration et l’heure de chaque observation. Remplacez les informations réelles par <UTILISATEUR>, <HÔTE>, <PROJET> et <CHEMIN> dans les documents partagés.

Rétablissez la session graphique et le bon domaine utilisateur

Sur macOS, le mode de service pris en charge par GitLab Runner repose sur un LaunchAgent associé à l’utilisateur connecté. Ce choix est déterminant : l’agent appartient à une session utilisateur, alors qu’un LaunchDaemon s’exécute dans un contexte système différent. La documentation GitLab précise que les opérations liées au service macOS doivent être réalisées depuis une session graphique locale, car le domaine utilisateur de launchctl doit être correctement initialisé.

Une installation ou un démarrage effectué exclusivement par SSH peut donc produire une erreur telle que launchctl failed: Could not find domain for. Le problème n’est pas forcément le fichier de configuration. Il peut simplement manquer le domaine graphique dans lequel l’agent doit être enregistré.

Procédez ainsi :

  1. Ouvrez la console web ou une session VNC fournie par votre opérateur, plutôt que de supposer que SSH reproduit le même contexte.
  2. Connectez-vous avec le compte qui doit exécuter le Runner. Vérifiez son identité avec la commande système appropriée et contrôlez qu’il s’agit bien du compte propriétaire du service.
  3. Lancez Terminal depuis cette session graphique.
  4. Consultez l’état du service et du domaine utilisateur avant toute suppression.
  5. Si le service a été installé dans le mauvais contexte, rechargez-le depuis cette session en suivant les commandes de la documentation GitLab.
  6. Fermez puis rouvrez la session, ou redémarrez le Mac uniquement après avoir conservé le fichier config.toml, le chemin du binaire et les journaux.
  7. Contrôlez à nouveau le processus, la dernière connexion dans GitLab et une tâche de test sans signature.

Point de vigilance : ne convertissez pas automatiquement un LaunchAgent en LaunchDaemon pour obtenir un démarrage « système ». Cette modification peut masquer la panne de session tout en cassant l’accès au trousseau, aux certificats ou au simulateur.

Un travail de compilation en ligne de commande, sans certificat ni interface graphique, peut parfois fonctionner dès que le processus est actif. Une tâche Xcode avec signature, accès au trousseau ou simulateur exige une analyse plus stricte. Apple décrit les composants de gestion des services et la relation entre agents et utilisateur connecté dans sa documentation Service Management.

Contrôlez le fichier plist, les chemins et les droits

Si la session est correcte mais que le Runner ne revient pas, inspectez les éléments qui empêchent un agent de se charger :

  • présence du fichier plist dans le répertoire LaunchAgents de <UTILISATEUR> ;
  • chemin absolu vers le binaire Runner ;
  • propriétaire et groupe du fichier de service ;
  • accès en lecture au fichier de configuration ;
  • droit d’écriture dans le répertoire de journaux ;
  • existence du répertoire parent ;
  • absence de chemin temporaire ou de volume non monté ;
  • cohérence entre le compte qui charge l’agent et le compte qui possède les fichiers.

Les erreurs citées par GitLab orientent la collecte, mais ne constituent pas à elles seules un diagnostic. killed: 9 peut indiquer qu’un processus a été interrompu ; exit status 134 signale une terminaison anormale ; Load failed: 5 indique un échec du chargement. Dans chaque cas, relevez l’heure exacte, le compte actif, la commande utilisée et les lignes précédentes du journal. Consultez aussi la documentation GitLab sur la configuration avancée avant de modifier une option.

Ne commencez pas par supprimer le plist ou à réenregistrer le Runner. Cette action peut détruire une piste utile et vous obliger à retrouver un jeton ou des paramètres qui fonctionnaient avant le redémarrage. La réinstallation est un dernier recours, réservé à un binaire manquant, à un fichier de service réellement endommagé ou à une installation dont l’intégrité est démontrée. Avant cette étape, copiez la configuration et documentez la procédure de réenregistrement.

Séparez connexion, enregistrement et étiquettes CI

Un Runner peut être démarré mais incapable de joindre GitLab. Dans ce cas, examinez les journaux du processus et comparez leur chronologie avec l’heure de dernière connexion affichée dans l’interface. Recherchez un délai d’attente, une erreur de proxy, un certificat non accepté, une résolution DNS incorrecte ou une horloge désynchronisée. Ne modifiez pas simultanément le proxy, le certificat et la configuration du Runner : vous ne saurez plus quelle action a résolu le problème.

Vérifiez ensuite l’enregistrement. Un service local peut utiliser une configuration qui ne correspond plus au projet, au groupe ou à l’identité attendue. La réinscription n’est justifiée qu’après avoir établi que le fichier de configuration, l’URL et le jeton autorisé ne sont plus valides. Si le Runner est partagé entre plusieurs projets, traitez le jeton comme une information sensible et limitez les copies dans les scripts et les tickets.

Enfin, analysez les étiquettes. Le Runner peut être parfaitement en ligne alors que le pipeline reste en attente, parce que la tâche réclame une étiquette absente du nœud ou parce que les règles du projet l’excluent. La documentation GitLab sur les étiquettes et l’affectation des tâches explique cette correspondance. Comparez les valeurs déclarées dans le pipeline avec celles visibles dans la configuration du Runner, sans ajouter une étiquette générique qui enverrait une tâche sensible vers un nœud inadapté.

Le choix de l’exécuteur compte aussi. Avec Shell executor, le script s’exécute avec les droits du compte Runner. Un projet compromis ou une dépendance non maîtrisée peut alors lire des fichiers, des variables ou des clés accessibles à ce compte. La documentation de sécurité de GitLab pour Shell executor recommande de réserver ce modèle aux projets de confiance. Sur un nœud partagé, isolez les projets, les répertoires de travail et les identifiants ; ne considérez pas la simple présence d’un Runner en ligne comme une frontière de sécurité.

Traitez FileVault sans affaiblir la sécurité

Après l’activation de FileVault, un redémarrage peut laisser le Mac au stade du déverrouillage du disque. Le système n’a alors pas ouvert la session graphique de l’utilisateur, même si votre architecture prévoit normalement un accès distant. Apple documente les contraintes de l’ouverture automatique de session, notamment lorsqu’un chiffrement du disque ou une politique d’organisation intervient dans la documentation consacrée à l’ouverture automatique de session.

La bonne décision dépend de la tâche :

  • pour une compilation sans trousseau, testez si le Runner peut fonctionner après ouverture de session manuelle ;
  • pour la signature, vérifiez le trousseau, le certificat et l’autorisation de la clé ;
  • pour un simulateur, confirmez que la session graphique et les composants nécessaires sont disponibles ;
  • pour un nœud administré, demandez l’accord de l’équipe sécurité avant toute modification de FileVault ou d’ouverture automatique.

Préparez un canal de secours avant le prochain redémarrage : console web ou VNC en plus de SSH, compte d’administration distinct, procédure de déverrouillage approuvée et journal de reprise. Si votre fournisseur ne permet pas cette double gestion, le nœud est difficile à exploiter pour une chaîne de publication qui doit reprendre à distance.

Validez la reprise avec une vraie tâche Xcode

Une simple commande qui retourne un code nul ne suffit pas à déclarer le nœud réparé. Faites un test isolé en respectant cette séquence :

  1. Terminez une tâche ordinaire et conservez son journal.
  2. Vérifiez que le répertoire de travail ne contient pas de certificat, de jeton ou de fichier de projet confidentiel résiduel.
  3. Redémarrez le Mac depuis le canal d’administration documenté.
  4. Vérifiez l’accès SSH, puis l’état de la session graphique.
  5. Contrôlez le chargement du LaunchAgent, le processus Runner et les journaux.
  6. Attendez la reconnexion visible dans GitLab avant de lancer une tâche de publication.
  7. Exécutez une compilation sans signature.
  8. Exécutez ensuite une tâche de signature et, séparément, un test nécessitant le simulateur.
  9. Notez pour chaque tâche le résultat, l’utilisateur, l’étiquette, le contexte graphique et l’heure de reprise.

Cochez chaque condition dans votre fiche d’acceptation :

  • [ ] Le Mac est accessible par SSH après redémarrage.
  • [ ] La console web ou VNC permet d’ouvrir la session autorisée.
  • [ ] Le LaunchAgent est chargé dans le domaine de l’utilisateur attendu.
  • [ ] Le processus Runner reste actif après la reconnexion.
  • [ ] GitLab reçoit une nouvelle communication du Runner.
  • [ ] Une tâche correspondant aux étiquettes du nœud est acceptée.
  • [ ] Une compilation sans signature aboutit.
  • [ ] Le trousseau et le certificat sont utilisables dans la tâche prévue.
  • [ ] Le simulateur démarre si le pipeline en dépend.
  • [ ] Les journaux ne révèlent ni secret ni chemin sensible partagé.
  • [ ] La procédure de reprise est reproductible par une autre personne.

Si seule la compilation sans interface réussit, conservez une réserve opérationnelle : ce n’est pas une validation complète pour une chaîne iOS. Vous pouvez décider de maintenir le nœud pour les tâches en ligne de commande et de réserver les signatures à un autre nœud, plutôt que de déclarer la réparation terminée.

FAQ de dépannage ciblé

Pourquoi le Runner ne revient-il pas après un redémarrage ?

Le redémarrage ne recrée pas nécessairement une session graphique utilisable par l’utilisateur du Runner. Comme le service macOS repose sur un LaunchAgent, l’absence de connexion, un domaine launchctl incorrect ou un blocage FileVault peut empêcher le chargement. Vérifiez ces éléments avant le réseau ou la réinscription, puis distinguez les tâches ordinaires de celles qui utilisent le trousseau ou le simulateur.

Pourquoi SSH ne trouve-t-il pas le domaine launchctl ?

Une session SSH n’est pas équivalente au Terminal ouvert dans la session graphique macOS. Le domaine utilisateur nécessaire au LaunchAgent peut donc ne pas être disponible. Utilisez VNC ou la console web pour ouvrir la session prévue, inspectez d’abord le service existant, puis rechargez-le dans ce contexte. Ne supprimez pas la configuration simplement parce que la commande échoue via SSH.

Pourquoi une tâche reste-t-elle en attente avec un Runner en ligne ?

L’état « en ligne » concerne la communication du Runner, pas l’admissibilité de chaque tâche. Une étiquette différente, une règle de pipeline restrictive ou un projet non autorisé peut empêcher l’affectation. Comparez la déclaration du travail, les étiquettes du Runner et les règles d’exécution. Cette vérification évite de redémarrer inutilement un service qui fonctionne.

Que faire si FileVault bloque le Runner distant ?

Commencez par confirmer si le Mac attend un déverrouillage avant d’ouvrir la session. Utilisez un canal console autorisé et documentez l’intervention. Ne désactivez pas FileVault par automatisme : l’ouverture automatique peut être incompatible avec la politique de sécurité. Validez ensuite séparément l’accès au trousseau, la signature et le simulateur, car une compilation simple peut réussir alors que la publication échoue.

Choisissez une architecture que vous pouvez réellement reprendre

Un Mac physique conservé au bureau offre un accès direct, mais il dépend de l’alimentation, de la connexion montante, du redémarrage manuel et de la disponibilité de la personne qui l’administre. Une machine virtuelle ou un serveur non macOS peut simplifier certaines tâches, mais ne remplace pas l’accès aux outils Apple, au trousseau ou au simulateur. Un nœud distant avec double accès SSH et console graphique est plus adapté lorsque vous devez reproduire un redémarrage sans présence locale.

Si vous évaluez un Mac mini distant pour la CI, ne comparez pas uniquement le processeur ou le prix. Demandez comment ouvrir la session graphique, comment récupérer un écran bloqué par FileVault, quelle identité possède le LaunchAgent et comment conserver les journaux. L’architecture est acceptable seulement si la procédure d’urgence est testable avant la migration.

Après le diagnostic, le choix entre votre solution actuelle et une location MACCOME se joue surtout sur la reprise : un Mac local peut rester inaccessible après une coupure, un serveur non macOS ne couvre pas les exigences de signature et une infrastructure sans console graphique rend les erreurs de session difficiles à corriger. Une location MACCOME vous donne un Mac distant administrable par SSH et par interface graphique, ce qui permet de reproduire le redémarrage, de restaurer la session et de vérifier le Runner avant d’y confier une publication. Pour un besoin temporaire, un nœud de test ou une capacité de secours, cette approche est généralement plus souple qu’un achat immédiat ; pour une charge stable nécessitant un accès physique permanent, conservez plutôt une machine dédiée sur site.