GitLab Runner hors ligne après redémarrage de macOS ? Guide de correction 2026

Un Mac peut répondre au réseau, accepter une connexion SSH et rester inutilisable pour une tâche iOS. À l’inverse, la page GitLab peut afficher un Runner reconnecté alors que la signature ou le simulateur échoue dès la première commande.

Nous séparons donc le diagnostic en quatre contrôles :

Ce découpage évite la fausse réparation la plus fréquente : relancer l’installation alors que le problème vient d’une session absente ou d’un compte différent. La documentation Apple sur les jobs launchd rappelle que le lancement dépend du domaine dans lequel le job est chargé. Un agent utilisateur et un démon système ne disposent donc pas du même contexte.

Pourquoi GitLab Runner ne redémarre-t-il pas automatiquement sur Mac ?
Parce que le démarrage du système ne crée pas nécessairement la session du compte CI. Si le Runner a été installé sous un autre compte, si le LaunchAgent n’est pas chargé dans le domaine utilisateur attendu ou si FileVault bloque l’accès avant ouverture de session, le processus ne peut pas reprendre son rôle normal. La panne se situe alors avant GitLab, même si l’interface web affiche simplement « hors ligne ».

Première étape : relever les preuves avant toute modification

Dans une fenêtre SSH contrôlée, nous relevons d’abord l’identité et l’état du service :

whoami
id -u
gitlab-runner status
launchctl print gui/$(id -u)

Ces commandes ne réparent rien. Elles permettent de répondre à trois questions : sommes-nous connectés avec le compte CI prévu, quel est son identifiant de session, et le LaunchAgent existe-t-il dans ce domaine ? Nous comparons ensuite le résultat avec le compte qui a installé GitLab Runner et avec le chemin réel de sa configuration.

Les sorties doivent être conservées dans le ticket d’incident, après suppression des jetons et des variables sensibles. Les recommandations de dépannage GitLab Runner demandent d’éviter l’exposition de secrets dans les journaux de diagnostic.

Sur macOS, GitLab Runner est pris en charge comme service utilisateur. Le fichier de lancement et la configuration doivent appartenir au compte qui exécutera les tâches. Le chemin exact dépend de la méthode d’installation ; nous vérifions donc la présence du fichier dans le répertoire Library/LaunchAgents du compte concerné, au lieu de supposer qu’un fichier placé dans un répertoire système sera équivalent.

La documentation Apple sur les agents et les démons distingue explicitement les services attachés à un utilisateur des services système. Remplacer un LaunchAgent par un LaunchDaemon peut donner l’impression d’avoir résolu le démarrage, tout en supprimant le contexte nécessaire aux tâches de compilation.

macOS GitLab Runner doit-il obligatoirement disposer d’une session utilisateur ?
Pour le mode macOS documenté par GitLab, oui : le LaunchAgent est lié à la session du compte qui l’exécute. La présence d’un processus ne suffit pas à prouver qu’il possède le trousseau de connexion, les variables de session, le contexte graphique ou les droits nécessaires à Xcode.

Peut-on convertir GitLab Runner en LaunchDaemon ?
Nous ne le recommandons pas pour corriger un redémarrage. Cette conversion modifie le domaine de lancement et sort de la forme de service documentée pour macOS. Si une politique impose un service système, il faut traiter cette décision comme une nouvelle architecture, avec validation séparée de la signature, du Keychain, du simulateur et de la sécurité des secrets.

Deux comptes ressemblants, un seul service exploitable

Les environnements d’entreprise accumulent parfois un compte administrateur, un compte d’exploitation et un compte CI. Une installation répétée sous plusieurs identités crée des configurations concurrentes, plusieurs fichiers LaunchAgent ou des identifiants system_id difficiles à relier à la bonne machine.

Nous vérifions alors :

• le compte propriétaire du fichier de configuration ;
• le compte ayant enregistré le Runner ;
• l’utilisateur visible dans la session active ;
• le nombre de services ou processus liés à GitLab Runner ;
• le projet ou le groupe auquel le Runner est réellement affecté.

Le routage doit ensuite être examiné séparément. Les règles GitLab relatives aux balises et à la configuration des Runners expliquent qu’un Runner disponible peut ne recevoir aucune tâche si ses balises, son périmètre ou les règles de branche protégée ne correspondent pas.

Un Runner « hors ligne » appelle une action de service. Un Runner en ligne sans tâche appelle souvent une action de routage. Confondre les deux conduit à redémarrer inutilement le Mac.

FileVault introduit une décision de sécurité qui ne peut pas être masquée par un simple script. Tant que le volume système n’est pas déverrouillé, macOS ne peut pas atteindre normalement le compte CI ni son LaunchAgent. L’ouverture automatique, elle, suppose qu’un chemin de connexion automatique soit autorisé.

La documentation Apple sur l’ouverture de session automatique et celle consacrée à la gestion de FileVault doivent être lues ensemble. Nous ne traitons pas le chiffrement du disque et la connexion sans intervention comme deux options toujours compatibles.

Comment récupérer à distance un Mac Runner protégé par FileVault ?
Nous commençons par vérifier le modèle matériel, la version macOS, la gestion de l’appareil, la disponibilité du réseau avant la session et la configuration de Remote Login. Apple documente l’activation de Remote Login, mais cette capacité ne prouve pas que le volume FileVault est déjà déverrouillé ni qu’une session CI est ouverte.

La décision doit être écrite dans le dossier d’exploitation : qui peut déverrouiller, par quel canal, avec quelle trace et quelle procédure de retrait en cas de départ d’un opérateur ? Une adresse de récupération partagée dans un document non contrôlé n’est pas une procédure d’entreprise.

Le service peut se reconnecter avant que les éléments nécessaires à une livraison soient accessibles. Nous séparons donc quatre essais, du moins sensible au plus représentatif :

Pour le contrôle du trousseau, nous identifions d’abord le compte d’exécution et l’état de la session, puis nous lançons une tâche de test qui ne publie rien. Une commande de recherche d’identités peut confirmer la présence d’une identité, mais elle ne prouve pas que le profil, le certificat et les autorisations correspondent à la cible de production.

Nous maintenons une séparation stricte entre :

• le trousseau de connexion du compte CI ;
• le trousseau système ;
• les certificats de signature ;
• les profils de provisioning ;
• les jetons d’enregistrement GitLab ;
• les personnes autorisées à modifier ces éléments.

Une tâche de publication complète est un mauvais premier test : elle mélange dépendances, signature, accès réseau et règles de distribution. Un échec court et ciblé fournit une preuve plus exploitable.

Checklist de remise en service

• [ ] Confirmer le compte CI avec whoami et conserver la preuve dans le ticket.
• [ ] Vérifier que le disque est déverrouillé selon la procédure FileVault approuvée.
• [ ] Confirmer l’existence d’une session utilisateur correspondant au compte d’exécution.
• [ ] Contrôler le statut GitLab Runner sans supprimer sa configuration.
• [ ] Inspecter le LaunchAgent dans le domaine utilisateur attendu.
• [ ] Vérifier qu’aucune installation concurrente ne pointe vers un autre compte.
• [ ] Comparer les balises du Runner avec celles du projet et de la branche protégée.
• [ ] Exécuter un script simple, puis un test Xcode sans publication.
• [ ] Tester séparément le simulateur et l’accès au Keychain.
• [ ] Contrôler qu’aucun secret n’apparaît dans les journaux.
• [ ] Documenter le résultat, l’heure, l’opérateur et l’action de retour arrière.
• [ ] Répéter l’essai après un redémarrage planifié avant de remettre le nœud en production.

Un statut « en ligne » est une condition nécessaire, pas un critère d’admission. Nous validons au minimum trois scénarios : redémarrage planifié, interruption électrique simulée selon la politique de l’entreprise et retrait contrôlé du compte ou d’une autorisation.

Pour chaque scénario, le registre doit distinguer :

1. la machine visible sur le réseau ;
2. le disque disponible ;
3. la session CI ouverte ;
4. le LaunchAgent chargé ;
5. le Runner capable d’accepter une tâche ;
6. le test Xcode terminé ;
7. le Keychain utilisé sans erreur ;
8. le routage vers le bon projet ;
9. la décision de remise en production ou de bascule.

Nous ne promettons pas de délai de récupération ni de taux de réussite sans mesure propre à l’environnement. Les versions macOS, l’architecture matérielle, la gestion des appareils et la politique réseau peuvent modifier chaque étape. Un rapport d’entreprise doit donc conserver les temps réellement observés, plutôt que reprendre une valeur générique.

Cette vérification est particulièrement importante pour les équipes audio, vidéo et design qui utilisent une chaîne Apple partagée : un Runner actif peut encore échouer lorsqu’un outil graphique, un plugin ou un trousseau lié à la session manque. Pour les besoins de capacité temporaire, un Mac distant MESHLAUNCH disponible pour les équipes peut être évalué comme nœud isolé, sans remplacer la validation de sécurité du pipeline principal.

Une architecture de secours mérite aussi une procédure indépendante. Une seconde machine ne sert pas de réserve si son compte CI, ses certificats, ses versions Xcode et ses balises n’ont jamais été testés. Nous documentons la copie autorisée des dépendances, la rotation des secrets et le retrait du nœud après l’incident. Pour comparer une capacité dédiée selon la région, les équipes peuvent examiner les options de Mac distant MESHLAUNCH, puis vérifier les conditions réelles de leur politique d’accès.

Un Mac acheté localement conserve l’avantage du contrôle physique, mais il laisse souvent à l’entreprise l’achat initial, le remplacement, la présence sur site et la reprise après panne. Un nœud distant autogéré ajoute les mêmes responsabilités auxquelles s’ajoutent l’accès réseau et le déverrouillage après incident. Si la reprise dépend encore d’une personne présente devant la machine, une capacité MESHLAUNCH séparée peut offrir une voie plus simple pour tester un nœud de secours ou absorber un besoin temporaire, à condition de conserver l’isolement des comptes, la validation du Keychain et les preuves d’exploitation.

La bonne décision n’est donc pas de forcer GitLab Runner à fonctionner comme un démon système. Elle consiste à prouver, dans l’ordre, le déverrouillage, la session, le LaunchAgent, le compte, le routage et la capacité réelle de compilation. Si votre Mac actuel ne passe pas cette chaîne sans intervention locale, évaluez une machine distante isolée comme relais de continuité, puis validez-la avec la même checklist avant de lui confier une publication.