Le Runner GitLab macOS est hors ligne après un redémarrage ? Connectez d’abord le compte utilisateur qui l’exécute, puis vérifiez le LaunchAgent et la connexion du Runner à GitLab. N’activez pas l’ouverture de session automatique avant d’avoir évalué le risque lié à l’accès physique et aux identifiants présents sur le Mac.
Ce guide s’adresse aux développeurs nomades qui doivent remettre en route une compilation iOS depuis un Mac distant, aux indépendants dont le Runner dépend d’une session macOS et aux petites équipes qui organisent leur continuité de construction.
Distinguer une panne de planification d’un Runner réellement hors ligne
Un message indiquant qu’aucun Runner n’est disponible ne prouve pas, à lui seul, que le Mac est arrêté. Le travail peut être bloqué avant d’atteindre l’hôte : le Runner peut être hors ligne, les étiquettes du travail peuvent ne pas correspondre, ou le Runner peut ne pas être autorisé pour le projet. Commencez par observer GitLab avant de modifier le Mac.
Dans le projet concerné, ouvrez la section des Runners et vérifiez si le Runner attendu est visible, actif et autorisé à prendre en charge les travaux. Comparez ensuite les étiquettes définies pour le travail à celles du Runner. GitLab indique que les étiquettes servent à faire correspondre les travaux aux Runners ; une étiquette requise absente peut donc empêcher la planification même si le processus local fonctionne. Consultez les règles GitLab de correspondance des étiquettes.
Pour éviter de confondre les symptômes, séparez les étapes du trajet d’un travail :
| Observation | Ce qu’elle indique | Vérification suivante |
|---|---|---|
| Le Runner est affiché hors ligne dans GitLab | Le Mac n’a peut-être pas de processus Runner actif, ou celui-ci ne parvient pas à joindre GitLab | Contrôler le compte connecté, le service et les journaux locaux |
| Le Runner est en ligne, mais le travail reste en attente | La planification peut être empêchée par les étiquettes, l’autorisation du projet ou les contraintes du travail | Comparer les réglages du Runner et la configuration du travail |
| Le travail démarre puis échoue | Le Runner reçoit le travail, mais son environnement ou ses droits peuvent être insuffisants | Lire les journaux du travail et vérifier le compte d’exécution |
| Le travail réussit, mais la compilation iOS échoue | Le service et la planification fonctionnent ; le problème se situe dans l’environnement Xcode ou le projet | Examiner les outils actifs, les composants requis et la sortie de compilation |
Pour confirmer le statut côté GitLab, comparez l’interface du projet aux champs d’état exposés par l’API GitLab des Runners. Cette vérification aide à distinguer un Runner absent ou hors ligne d’un Runner disponible mais mal sélectionné. Elle ne remplace pas le contrôle sur l’hôte : les deux observations doivent raconter la même histoire avant de conclure.
Vérifier le compte macOS et le LaunchAgent
La documentation GitLab pour macOS décrit un Runner lancé comme agent de lancement de l’utilisateur. Ce mode est associé à une session utilisateur : un redémarrage qui laisse le Mac à l’écran de connexion ne garantit donc pas que le Runner a repris. Consultez la procédure officielle d’installation de GitLab Runner sur macOS avant de modifier son mode de lancement.
Sur le Mac, connectez-vous au compte qui a installé et exécute le Runner. Confirmez qu’il s’agit bien du compte attendu, et pas d’un autre utilisateur administrateur. Un agent démarré dans une session différente n’équivaut pas nécessairement à l’environnement qui contient le Runner, ses fichiers de configuration, ses certificats et ses outils de développement.
Depuis le répertoire où se trouve l’exécutable, utilisez la commande d’état prévue par GitLab :
./gitlab-runner status
Si votre installation utilise une commande accessible depuis le chemin système, invoquez l’exécutable correspondant sans le préfixe de répertoire. Vérifiez également si le service a été installé et démarré avec les commandes prévues pour votre mode d’installation ; GitLab documente les commandes de service, notamment l’installation, le démarrage, l’arrêt et l’état, dans sa référence des commandes Runner.
L’état local peut fournir des indices, mais ne démontre pas à lui seul que GitLab reçoit les signaux du Runner. Gardez la page du projet ouverte en parallèle et observez si son statut évolue après une connexion de l’utilisateur et le démarrage du service. Si le service paraît actif et que GitLab le signale toujours hors ligne, passez au contrôle de la connexion, du fichier de configuration et des journaux plutôt que de réinstaller sans diagnostic.
Un LaunchAgent ne doit pas être assimilé à un service système qui se lancerait indépendamment d’une session utilisateur. Si votre plan de reprise suppose un Mac laissé à l’écran de connexion, testez-le explicitement : ne déduisez pas le comportement d’une session SSH restée ouverte.
Comprendre ce que changent redémarrage, déconnexion et coupure SSH
Ces événements ne sont pas interchangeables. Une coupure SSH ferme une connexion distante, mais ne prouve pas à elle seule que la session graphique de l’utilisateur est terminée. Une déconnexion de l’utilisateur modifie cette session. Un redémarrage, lui, arrête les processus et oblige le Mac à revenir dans un état de démarrage où l’agent peut ou non se relancer selon son installation et la session disponible.
Pour localiser la panne, réalisez des contrôles séparés, dans un environnement où l’interruption est acceptable :
- Après une coupure SSH, vérifiez si le compte graphique est toujours connecté et si GitLab voit encore le Runner.
- Après une déconnexion macOS, contrôlez le service local puis le statut dans GitLab ; notez si le Runner a cessé de fonctionner ou s’il ne peut simplement pas reprendre.
- Après un redémarrage, observez si le compte est connecté, si le service démarre et si le Runner revient en ligne sans intervention.
- Après le retour en ligne, soumettez un travail de test autorisé afin de vérifier que le Runner peut réellement le prendre en charge.
Consignez les résultats avec l’heure, le compte utilisé, l’état local du service, le statut GitLab et le résultat du travail. Cette trace est plus utile qu’une impression comme « le Runner ne marche plus », surtout lorsque vous administrez le Mac depuis un autre fuseau horaire ou un réseau peu fiable. Si le Runner est en ligne avant une déconnexion puis devient hors ligne après, la dépendance à la session devient un indice sérieux ; elle ne dispense toutefois pas de confirmer le mode de service et les journaux.
Choisir une reprise adaptée au niveau de risque
Une ouverture de session automatique peut sembler être le raccourci évident : si le LaunchAgent attend une session, le Mac tente de la rétablir sans intervention humaine. La documentation GitLab mentionne cette possibilité dans le contexte du démarrage du Runner sur macOS. Cela ne signifie pas qu’elle convient à tous les hôtes ni qu’elle constitue une garantie de reprise. Apple décrit aussi les conditions et implications de l’ouverture de session automatique sur Mac.
Avant de l’envisager, vérifiez qui peut accéder physiquement au Mac, comment le compte utilisateur est protégé et quels secrets le Runner peut lire. Un compte automatiquement ouvert sur une machine accessible à des tiers peut exposer des données de projet, des certificats ou des sessions encore valides. À l’inverse, si l’accès physique est strictement contrôlé et que la reprise sans intervention est indispensable, cette option peut faire partie d’un plan évalué et documenté. Il n’existe pas de promesse de sécurité valable indépendamment de la configuration et du contexte.
| Option de reprise | Atout principal | Limite à évaluer | Choisissez-la si… |
|---|---|---|---|
| Connexion manuelle puis lancement contrôlé | Vous gardez la décision d’ouvrir la session et de démarrer le Runner | Quelqu’un doit intervenir après un redémarrage | Les travaux peuvent attendre et vous privilégiez le contrôle d’accès |
| Ouverture de session automatique | Peut fournir la session attendue par le LaunchAgent | Élargit les conséquences d’un accès physique ou d’un compte compromis | Vous avez évalué et accepté ce risque, avec une protection adaptée |
| Chemin de construction de secours | Permet de livrer si le Mac principal n’est pas prêt | Implique un environnement alternatif à configurer et à maintenir | Une interruption de compilation est plus coûteuse que la maintenance du secours |
| Remplacement par une autre organisation de construction | Peut mieux correspondre aux contraintes d’exploitation de l’équipe | Demande de valider les capacités requises pour le projet | La dépendance à une session interactive est incompatible avec vos objectifs |
Cette comparaison concerne la reprise, pas la qualité d’une offre d’hébergement ni la compatibilité garantie d’un environnement particulier. Avant de changer d’architecture, examinez aussi les contraintes de signature, les dépendances du projet et les outils requis. Si vous évaluez un Mac distant pour votre environnement de développement, vérifiez les modalités d’accès et confirmez que le mode d’administration répond à votre procédure de reprise ; ne présumez pas que chaque Mac distant se comporte comme votre installation actuelle.
Contrôler le Runner en ligne sans confondre disponibilité et compilation
Un Runner affiché en ligne ne prouve pas que le travail visé sera accepté. Il ne prouve pas non plus que le travail aboutira, ni que Xcode pourra produire le résultat attendu. Traitez ces constats comme des validations distinctes : le processus est-il démarré ? GitLab peut-il lui attribuer le travail ? Le travail s’exécute-t-il sous le bon compte ? Enfin, la compilation réussit-elle ?
Si le travail reste en attente, comparez ses étiquettes avec celles du Runner et vérifiez son autorisation pour le projet. Les réglages d’étiquettes sont définis dans la configuration du travail et du Runner ; suivez les consignes de configuration des Runners GitLab plutôt que de retirer des contraintes au hasard. Un Runner actif mais inadmissible pour ce travail est un problème de sélection, pas un problème de redémarrage.
Si le travail commence, lisez le journal avant de changer les droits. Repérez le compte d’exécution, le répertoire du projet, les commandes effectivement lancées et l’erreur précise. Une compilation peut échouer parce que le processus ne retrouve pas un outil, n’a pas accès à un fichier requis ou n’utilise pas l’environnement prévu. Élargir les autorisations sans identifier la ressource concernée peut exposer davantage de données sans corriger le défaut.
Pour Xcode, vérifiez que les outils en ligne de commande sont disponibles et que le répertoire de développement sélectionné correspond à l’installation attendue. Apple présente l’installation des outils en ligne de commande Xcode séparément de l’installation de composants complémentaires ; certains projets peuvent dépendre de composants à installer depuis Xcode, décrits dans la documentation Apple sur le téléchargement et l’installation de composants Xcode supplémentaires. Basez votre diagnostic sur le message du journal et les exigences du projet, pas sur la seule présence de l’application Xcode.
Si l’interface GitLab indique que le Runner est actif, mais que les travaux échouent toujours, l’observation utile est désormais le résultat du travail. Pour une compilation iOS, un contrôle ciblé doit confirmer que la commande de construction attendue démarre dans le bon répertoire, voit les outils nécessaires et se termine avec le résultat attendu. Une simple connexion au Mac par SSH ne valide ni ces permissions ni la session graphique.
Valider la procédure par une répétition complète
Ne considérez pas l’incident comme résolu parce que le Runner est revenu en ligne après une intervention manuelle. Avant de compter sur lui pendant un déplacement, testez le chemin de reprise prévu, idéalement sur un changement ou un travail de validation sans conséquence pour une livraison en cours.
Suivez cette séquence et consignez chaque résultat :
- Notez le mode d’installation du Runner et le compte macOS auquel il est associé.
- Vérifiez l’état de la session utilisateur avant de lancer le test.
- Redémarrez le Mac selon la procédure que vous utiliserez réellement, sans modifier en même temps les paramètres du Runner.
- Contrôlez si la session requise est ouverte et si le service Runner est démarré.
- Confirmez que GitLab affiche le Runner comme disponible, puis vérifiez qu’un travail correspondant à ses étiquettes est attribué.
- Lisez le journal du travail jusqu’à la fin et vérifiez le résultat de la compilation Xcode.
- Recommencez selon le scénario de déconnexion qui vous préoccupe si vous devez aussi connaître son effet.
Décidez à partir des observations. Conservez le Runner autogéré si le mode de reprise a été vérifié, que les contraintes de session sont acceptables et qu’un échec dispose d’un traitement défini. Ajustez le plan si une intervention humaine est possible, mais trop lente pour vos délais. Préparez un chemin de secours si vous ne pouvez pas accepter qu’une session reste ouverte ou si l’accès au Mac est incertain. Si l’organisation dépend d’une ouverture de session automatique dont le risque n’a pas été évalué, ne validez pas cette procédure comme solution simplement parce qu’un essai a réussi.
Pour les déplacements, gardez les informations de diagnostic accessibles sans dépendre du Mac concerné : compte d’exécution, emplacement des journaux, procédure de connexion, contact habilité et étape qui permet de basculer vers le secours. Cela évite qu’une perte d’accès au poste principal se transforme aussi en perte de la seule procédure de récupération.
FAQ sur le Runner GitLab macOS après redémarrage
Pourquoi le Runner ne revient-il pas en ligne après le redémarrage ?
Le point de départ est la session de l’utilisateur qui exécute le LaunchAgent. Connectez ce compte, contrôlez l’état local du service, puis comparez-le au statut du Runner dans GitLab. Si le service fonctionne mais que GitLab le voit hors ligne, vérifiez la connexion et les journaux avant de modifier l’installation.
Comment confirmer que le service Runner a démarré ?
Utilisez la commande d’état documentée par GitLab depuis le compte et l’installation concernés. Contrôlez ensuite que le LaunchAgent est présent dans le contexte de cet utilisateur, puis regardez le statut côté GitLab. La commande locale confirme un état du service, pas l’attribution d’un travail ni le succès d’une compilation.
Le Runner fonctionne-t-il après la déconnexion de l’utilisateur ?
Ne le déduisez pas d’une fermeture SSH. Vérifiez séparément l’état du compte graphique, du service local et du Runner dans GitLab après une déconnexion macOS contrôlée. Le comportement dépend du mode de lancement et de la session ; vos observations sur l’installation concernée doivent guider la procédure.
L’ouverture de session automatique permet-elle une reprise sans intervention ?
Elle peut rétablir la session dont dépend le LaunchAgent, mais elle ne garantit ni la reconnexion à GitLab ni la réussite d’un travail. Évaluez aussi l’accès physique, la protection du compte et les secrets disponibles sur le Mac. Si le risque est inacceptable, prévoyez une reprise manuelle ou un environnement de secours.
Si votre procédure confirme que le projet a besoin d’un environnement macOS accessible en continu, comparez honnêtement le Mac autogéré à une solution distante : le premier exige de surveiller les mises à jour, la session et les redémarrages ; une machine laissée chez vous reste dépendante de son alimentation et de sa connexion ; une ouverture automatique peut élargir les risques d’accès. Un Mac distant ne supprime pas le travail de validation du Runner, mais peut éviter de transporter le poste et maintenir un environnement accessible depuis un appareil léger. Si cette option correspond à vos contraintes, consultez les solutions de Mac distant proposées par MACCOME et vérifiez l’accès requis pour votre flux GitLab CI/CD avant de décider.