DevOps / CI/CD

Comment déployer GitLab Runner auto-hébergé sur macOS ? Guide 2026

Deux contextes launchd sont à distinguer sur macOS : l’agent utilisateur et le démon système, décrits par la documentation Apple sur les agents et les démons launchd. Pour GitLab Runner, la décision opérationnelle est nette : un Runner macOS peut exécuter des tâches avec le shell executor, mais il doit fonctionner comme LaunchAgent associé à un utilisateur, et non comme LaunchDaemon. Le shell executor lance les commandes sur l’hôte ; il faut donc réserver le nœud aux projets fiables et accepter ses limites d’isolement.

Ce guide est destiné aux équipes qui doivent ajouter des tâches Xcode ou des tests iOS à leurs pipelines, sans avoir encore configuré de Runner macOS. Il s’adresse aussi aux personnes qui administrent ce nœud depuis Windows ou Linux, ainsi qu’aux équipes qui évaluent un Mac distant pour leur intégration continue.

Choisir le bon périmètre avant de créer le Runner

Le Runner s’installe sur la machine qui exécute effectivement les scripts du pipeline. Si les tâches doivent utiliser macOS et Xcode, le nœud d’exécution doit donc disposer de l’environnement macOS et des dépendances du projet. En revanche, cela ne signifie pas qu’il faut installer l’instance GitLab elle-même sur ce Mac : le service de gestion du dépôt et l’agent d’exécution sont deux éléments distincts.

Avant d’engager un hôte, séparez les tâches qui nécessitent réellement Apple de celles qui peuvent continuer à s’exécuter sur les nœuds existants. Une compilation iOS, une étape dépendant de Xcode ou un test sur simulateur peut justifier un Runner macOS. Des contrôles indépendants de macOS peuvent rester sur un Runner Linux ou un autre environnement adapté. Cette répartition limite le nombre de travaux exposés au nœud Mac et rend le routage plus lisible.

Option Travaux adaptés Point de vigilance Décision
Runner macOS avec shell executor Scripts qui doivent utiliser les outils présents sur macOS, notamment la chaîne Xcode Les commandes s’exécutent localement avec les permissions du compte du Runner À retenir pour les tâches Apple si les projets autorisés sont fiables
Runner Linux Étapes qui ne dépendent pas d’outils macOS ni d’une session Apple Ne fournit pas l’environnement macOS requis par les tâches Xcode À conserver pour les étapes compatibles, sans lui attribuer les tâches Apple
Service GitLab hébergé sur un Mac Ce n’est pas une condition pour exécuter des tâches macOS Confond le service de gestion avec le nœud Runner Ne pas choisir cette architecture uniquement pour obtenir un environnement de compilation Mac

GitLab recommande le shell executor pour les constructions iOS et macOS dans sa documentation d’installation du Runner sur macOS. Cette recommandation répond au besoin d’exécuter des outils installés sur le Mac ; elle ne transforme pas le shell executor en environnement cloisonné. Le choix doit donc être évalué à la fois selon les outils nécessaires et selon la confiance accordée aux dépôts et aux scripts.

Vérifier que le nœud possède l’environnement d’exécution attendu

Le premier critère n’est pas que le Runner apparaisse comme actif dans l’interface, mais que l’hôte puisse exécuter une tâche représentative. Préparez les dépendances au niveau du Mac, puis consignez les résultats de contrôles qui permettront de distinguer un problème de Runner d’un problème de projet.

  • [ ] Le Runner est installé sur le Mac qui exécutera réellement les travaux, plutôt que sur une machine qui ne ferait que les relayer.
  • [ ] Les outils et dépendances du projet sont présents sur cet hôte et accessibles au compte du Runner.
  • [ ] Le Runner est enregistré auprès du bon projet ou groupe, conformément à la documentation GitLab sur l’enregistrement d’un Runner.
  • [ ] Un tag distinctif permet de réserver les tâches macOS à ce nœud.
  • [ ] Une tâche minimale confirme dans ses journaux quel Runner et quel environnement ont effectivement été sélectionnés.

Lors de l’enregistrement, choisissez un périmètre cohérent avec les personnes qui peuvent modifier la configuration CI. Un Runner partagé trop largement peut recevoir des travaux qui n’ont aucune raison d’accéder à un Mac doté d’outils ou de secrets Apple. Les indications GitLab sur la portée des Runners aident à déterminer si l’enregistrement doit être limité à un projet, à un groupe ou à une portée plus large.

Pour tester le routage, la configuration CI doit demander le tag associé au nœud macOS. Dans le journal du travail, vérifiez que le tag exigé a été satisfait et que le travail ne s’est pas exécuté sur un autre Runner. Si une tâche reste en attente, examinez d’abord la correspondance des tags et la disponibilité du Runner au lieu de modifier simultanément plusieurs paramètres. Cette séparation facilite le diagnostic et évite de conclure à tort que l’environnement Mac est défaillant.

Confirmer le fonctionnement en session utilisateur

Sur macOS, l’installation du service Runner doit respecter le mode documenté par GitLab : un LaunchAgent lié à un utilisateur, et non un LaunchDaemon système. La différence est importante pour l’exploitation quotidienne. Un agent utilisateur est associé au contexte de cet utilisateur, tandis qu’un démon relève du contexte système. La documentation Apple sur les tâches launchd décrit cette distinction, et la procédure GitLab pour macOS précise le mode à utiliser pour le Runner.

Le compte de service doit disposer des droits nécessaires aux tâches, sans recevoir des privilèges qui ne sont pas justifiés. Il faut également vérifier ce que signifie concrètement une déconnexion ou un redémarrage dans l’environnement prévu : le Runner est-il encore présent, le compte concerné a-t-il ouvert une session, et les travaux qui utilisent le trousseau ou une interface graphique sont-ils exécutables dans cet état ? Ces vérifications doivent être faites sur le nœud réel, car la réussite d’un travail non graphique ne prouve pas que le simulateur ou une interaction avec une session utilisateur fonctionnera de la même façon.

Une ouverture de session automatique peut améliorer la continuité de certains usages, mais elle change le modèle de sécurité du poste. Avant de l’activer, l’équipe doit déterminer quelles données et quels secrets deviennent accessibles dans cette session, qui peut redémarrer la machine et comment l’accès physique ou à distance est protégé. Ne traitez pas cette option comme un simple réglage de disponibilité : elle doit faire partie de l’évaluation des risques et des procédures de reprise.

Un Runner affiché comme disponible ne prouve ni que les tâches dépendant d’une session graphique fonctionneront après un redémarrage, ni que le compte possède le bon trousseau. Validez ces cas séparément, dans les conditions d’exploitation prévues.

Valider Xcode avec un travail représentatif

La présence de Xcode dans le répertoire des applications ne suffit pas à démontrer que la tâche CI utilisera la bonne chaîne d’outils. Il faut vérifier l’installation effective, le répertoire développeur actif et les composants nécessaires au projet. Apple documente l’installation des outils de ligne de commande ainsi que le téléchargement et l’installation de composants Xcode supplémentaires. Les exigences précises dépendent du projet et des outils appelés par ses scripts.

Organisez le contrôle autour de preuves inscrites dans le journal CI :

  • Vérifiez que les commandes prévues sont accessibles au compte du Runner, et non seulement au compte administrateur ayant préparé la machine.
  • Identifiez dans le travail la chaîne d’outils réellement invoquée et le répertoire développeur actif. Comparez ces informations avec les attentes du projet.
  • Exécutez une compilation représentative de la cible concernée, avec les dépendances effectivement utilisées par le dépôt.
  • Examinez le résultat et les journaux en cas d’échec, afin de distinguer une erreur de configuration Xcode d’un problème de routage ou de permissions.

Le contrôle de base ne doit pas être présenté comme une validation complète des fonctionnalités Apple. Une compilation réussie ne confirme pas à elle seule que le simulateur démarre dans le contexte de session du Runner, que l’étape de signature dispose des accès requis ou que les secrets sont isolés des autres travaux. Ajoutez des tests spécifiques pour ces capacités lorsque le pipeline en dépend, et limitez leur exécution aux projets et comptes autorisés.

Évaluer les limites du shell executor avant d’y envoyer des projets

Le shell executor exécute les commandes du travail directement sur l’hôte, avec le compte utilisé par le Runner. Il ne constitue donc pas une couche d’isolation équivalente à un conteneur. Les scripts et fichiers laissés par un travail peuvent avoir des conséquences sur les travaux suivants selon les permissions, l’organisation du répertoire de travail et la manière dont les secrets sont gérés. GitLab détaille ces risques dans sa documentation de sécurité des Runners et dans la description du shell executor.

Avant d’activer le nœud, l’équipe devrait répondre aux questions suivantes :

  • Les projets autorisés à cibler le Runner sont-ils contrôlés par des personnes de confiance ?
  • Les modifications de la configuration CI sont-elles examinées avant leur exécution sur le Mac ?
  • Le compte du Runner a-t-il uniquement les droits nécessaires aux compilations prévues ?
  • Les certificats, clés, jetons et éléments de trousseau peuvent-ils être lus par un autre travail exécuté sous le même compte ou sur le même nœud ?
  • Le nettoyage des espaces de travail et des fichiers temporaires est-il défini, vérifiable et compatible avec les besoins de diagnostic ?

Si les réponses révèlent qu’un dépôt non fiable peut exécuter du code ou accéder à des données qui ne lui sont pas destinées, ne compensez pas ce risque en ajoutant simplement des commandes de nettoyage au script. Réévaluez la séparation entre projets, comptes et nœuds, ainsi que l’architecture d’exécution disponible. La documentation GitLab sur la sécurité constitue le point de départ de cette analyse ; le shell executor reste un choix d’exécution local, pas une promesse de cloisonnement fort.

FAQ : lever les doutes de déploiement

Peut-on installer GitLab Runner sur un Mac sans y héberger GitLab ?

Oui. Le Runner doit se trouver sur la machine qui exécutera réellement les tâches, avec les outils nécessaires au projet. Le service GitLab n’a pas besoin d’être installé sur ce Mac. Pour un pipeline Apple, le critère est la disponibilité de l’environnement macOS et de Xcode pour le compte du Runner, et non l’emplacement du service qui gère les dépôts et les travaux.

Quel executor convient aux tâches iOS ou macOS ?

Pour les tâches de construction iOS et macOS, GitLab recommande le shell executor dans sa documentation consacrée à macOS. Il exécute les commandes sur l’hôte et peut donc utiliser les outils qui y sont installés. Cette facilité ne doit pas être confondue avec un isolement entre travaux : réservez le Runner aux projets dont les scripts et les personnes qui les contrôlent sont considérés comme fiables.

Pourquoi éviter un LaunchDaemon pour le Runner macOS ?

La procédure GitLab pour macOS demande un LaunchAgent associé à un utilisateur et indique que le LaunchDaemon système n’est pas pris en charge pour ce cas. Le contexte utilisateur peut influer sur l’accès à des fonctions qui dépendent d’une session, notamment certains usages du trousseau ou du simulateur. L’équipe doit vérifier les conséquences d’une déconnexion et d’un redémarrage, et décider si une ouverture de session automatique est acceptable.

Comment prouver qu’une compilation Xcode s’exécute sur le Mac distant prévu ?

Attribuez au Runner un tag réservé aux tâches macOS et faites demander ce tag par le travail CI. Le journal doit permettre de vérifier le Runner sélectionné, l’hôte d’exécution et les informations utiles sur la chaîne Xcode. Ajoutez ensuite une compilation qui représente réellement le projet, puis contrôlez ses artefacts et ses erreurs. Validez séparément les étapes de simulateur et de signature si elles sont requises.

Mesurer la disponibilité et préparer le retour en service

Une installation acceptée doit être vérifiée après les événements susceptibles d’interrompre l’exécution : fermeture de session, redémarrage, maintenance ou modification de l’environnement de développement. Le résultat attendu doit être écrit à l’avance pour chaque scénario. Par exemple, l’équipe peut exiger que le Runner redevienne disponible après une maintenance planifiée, ou décider qu’une intervention manuelle est nécessaire lorsque l’accès au compte utilisateur doit être rétabli.

Conservez des éléments qui rendent le diagnostic possible sans exposer les secrets : état du Runner, journaux utiles, tag attendu, résultat de la compilation témoin et procédure suivie lors de la dernière modification de la chaîne d’outils. Après une mise à jour de Xcode ou des dépendances, relancez le travail représentatif et confirmez que les outils actifs correspondent toujours à ce que le projet attend. Ne confondez pas une compilation témoin réussie avec la validation de toutes les capacités du pipeline.

La qualification du nœud doit aussi refléter son rôle réel. Un Runner utilisé pour un essai individuel n’a pas les mêmes exigences qu’un nœud d’équipe recevant des travaux contrôlés, ni qu’un maillon dont dépend une chaîne de livraison critique. Plus le pipeline dépend de ce Mac, plus la procédure de reprise, la surveillance des journaux, la gestion des accès et la responsabilité de maintenance doivent être explicites.

Décider si un Mac distant correspond au modèle d’exploitation

Un Runner auto-hébergé a besoin d’un nœud macOS accessible et maintenu selon les contraintes de l’équipe. Avant d’y déplacer une tâche, vérifiez les conditions d’accès, la période de disponibilité recherchée, les modalités de gestion de la session et la possibilité de préparer la chaîne d’outils requise. La console de KuzCloud et son centre d’aide permettent de consulter les informations de service effectivement disponibles ; elles ne remplacent pas la validation de votre propre travail CI.

Un Mac distant peut éviter l’achat et l’administration immédiate d’une machine locale lorsque le besoin porte sur un environnement temporaire ou une capacité de test à évaluer. Il ne supprime toutefois pas les obligations liées à la sécurité du shell executor, à la gestion des secrets ou à la continuité du compte utilisateur. À l’inverse, l’achat d’un Mac peut être plus cohérent si une équipe a besoin d’un poste durablement contrôlé, de périphériques physiques ou d’une configuration matérielle particulière. Un Runner Linux reste préférable pour les étapes qui ne nécessitent pas macOS.

Si l’alternative actuelle est un Mac partagé manuellement, des exécutions sur des postes de développeurs ou une infrastructure Linux incapable de fournir Xcode, les limites sont différentes mais concrètes : disponibilité dépendante des sessions et des usages locaux, environnement moins prévisible entre travaux, ou impossibilité d’exécuter les tâches Apple. Pour une expérimentation temporaire, la location d’un Mac auprès de KuzCloud peut être plus souple qu’un achat, à condition de vérifier d’abord les modalités d’accès et la période proposée, puis de faire passer le test de routage, de session et de compilation avant toute intégration à un pipeline important. Consultez les informations de KuzCloud et retenez le Mac distant uniquement si les conditions réelles correspondent au niveau de disponibilité et de contrôle exigé par vos travaux.

Exécutez vos pipelines CI/CD sur un Mac dédié avec KuzCloud

Louez un Mac mini M4 physique avec accès root complet pour configurer votre environnement macOS et vos outils de compilation selon vos besoins.

Construisez et testez vos applications avec Xcode sur une machine dédiée, sans ressources partagées ni surcharge de virtualisation.