GitLab CI Mac Runner : déploiement et validation 2026

Constat : GitLab classe l’exécuteur Shell en mode maintenance et précise que son isolation est limitée.
Action immédiate : le déploiement d’un runner Mac pour GitLab CI est possible, mais réservez d’abord le nœud à des projets de confiance et vérifiez la session utilisateur, Xcode et la reprise après redémarrage avant de l’ouvrir à l’équipe.

Cet article s’adresse à vous si vous développez pour iOS ou macOS et souhaitez exécuter compilation ou tests sur un Mac depuis GitLab CI.
Il concerne aussi les équipes DevOps responsables de l’enregistrement et de l’exploitation du nœud, ainsi que les responsables sécurité qui doivent en définir les limites.

SECTION 01Avant de préparer le Mac : votre pipeline justifie-t-il un nœud macOS ?

Un runner macOS n’a d’intérêt que pour les étapes qui ont réellement besoin de macOS ou des outils Apple. Vous pouvez conserver sur des exécuteurs généralistes l’orchestration, les tests indépendants de la plateforme et les tâches de préparation ; le nœud Mac prend alors en charge les compilations, tests et validations qui requièrent Xcode. Cette séparation évite de traiter le Mac comme un serveur universel et limite l’exposition de son environnement de développement.

GitLab documente l’installation de GitLab Runner sur macOS et mentionne l’exécuteur Shell pour les tâches de compilation iOS et macOS. Cela établit que l’architecture est prise en charge, mais ne signifie ni que chaque combinaison de versions est compatible avec votre projet, ni que l’environnement convient automatiquement à des tâches de production. Consultez la documentation officielle d’installation de GitLab Runner pour macOS avant de choisir la méthode adaptée à votre système.

Le point de vigilance principal est l’exécution des scripts dans le contexte du compte qui fait tourner le runner. Contrairement à une frontière d’isolation conçue pour enfermer chaque tâche, Shell exécute les commandes dans l’environnement macOS de l’hôte. GitLab signale les limites d’isolation de cet exécuteur et le place en mode maintenance ; examinez aussi la présentation des statuts des exécuteurs GitLab pour intégrer cet état dans votre décision.

Avant de poursuivre, séparez ces cas :

À essayer sur un nœud dédié : dépôt contrôlé par votre équipe, scripts examinés, accès aux secrets limité et possibilité de retirer le Mac du pool si un contrôle échoue.
À exclure de ce nœud par défaut : contributions non fiables, projets sans propriétaire clair, ou tâches dont les scripts peuvent accéder aux données d’autres projets.
À revoir avant usage : pipeline partagé entre équipes, compte personnel utilisé pour la session macOS, ou tâches de signature qui exposent des certificats et des trousseaux sensibles.

GitLab Runner peut-il être installé sur macOS ? Oui, en suivant la procédure officielle ; cette possibilité ne règle toutefois ni la question de l’isolation ni celle de la persistance de la session. Le choix de l’exécuteur ne se réduit donc pas à une préférence de configuration : pour des travaux Apple nécessitant un environnement macOS, Shell est le chemin décrit par GitLab, mais il faut accepter son modèle de sécurité et réserver le nœud aux tâches de confiance. Si ce modèle ne correspond pas à votre risque, suspendre le déploiement partagé est une décision valide.

SECTION 02Étape de préparation : créez une base macOS traçable

Avant l’installation, désignez le rôle du Mac et le compte qui exécutera les travaux. Évitez de transformer une machine de travail personnelle en runner partagé : le compte peut contenir des clés, des sessions d’applications, des dépôts clonés et des éléments du trousseau sans rapport avec le pipeline. Utilisez un nœud réservé, un compte d’exécution explicite et une procédure de retrait qui permette de désactiver le runner sans perturber les postes des développeurs.

Consignez la provenance et la configuration de l’environnement dans un emplacement accessible à l’équipe d’exploitation : système installé, compte de service prévu, méthode de lancement, projets autorisés, étiquettes du runner et procédure de retour arrière. Relevez les versions réellement présentes sur le nœud au moment de l’installation, plutôt que de recopier une version supposée dans un document de configuration. Les combinaisons de GitLab Runner, macOS et Xcode doivent être vérifiées pour votre environnement et votre projet ; ne déduisez pas une compatibilité de la seule présence d’un binaire.

Préparez ensuite l’outillage requis par le dépôt. Si le projet exige Xcode, installez la version autorisée par votre équipe et vérifiez que les outils en ligne de commande sont disponibles. Apple décrit les outils de ligne de commande et leur installation dans sa documentation Xcode dédiée. Le référentiel des commandes Xcode aide à identifier les contrôles adaptés à votre chaîne.

Sur le Mac, relevez au minimum le chemin actif des outils et les informations de version renvoyées par :

xcode-select -p
xcodebuild -version
xcodebuild -showsdks

Ces commandes ne prouvent pas qu’une compilation du projet fonctionnera ; elles établissent quel environnement la session courante expose. Si le dépôt impose une version précise, vérifiez que le chemin sélectionné pointe vers l’installation attendue et que le compte du runner obtient le même résultat que le compte utilisé pendant votre vérification. Un terminal ouvert sous un autre utilisateur n’est pas une preuve suffisante.

Pensez également au cas créatif, souvent négligé dans une conception de CI centrée sur la compilation. Une équipe audio ou vidéo peut avoir une étape macOS qui exporte un média, vérifie un projet ou produit un artefact associé à une application Apple. Ne supposez pas que la seule présence de Xcode couvre ces outils, ni qu’un travail exécuté en arrière-plan bénéficie des mêmes ressources ou autorisations qu’une session graphique. Répertoriez chaque application et chaque ressource requise, puis essayez le traitement réel sous le compte d’exécution avant de l’inclure dans le pipeline partagé.

Le contrôle du poste doit laisser une trace consultable : identité du compte, outils disponibles, répertoire de développement sélectionné, espace de travail prévu et règle d’effacement des fichiers après un travail. Si une information n’est pas observable dans l’environnement d’exécution, notez-la comme inconnue ; ne la remplacez pas par une hypothèse dans le dossier d’exploitation.

SECTION 03Étape d’installation : enregistrez le runner et choisissez ses limites

Installez GitLab Runner selon la procédure macOS officielle, puis enregistrez-le dans le projet ou le périmètre GitLab qui correspond à votre politique d’accès. La documentation d’enregistrement des runners décrit le processus et les informations à fournir. Utilisez un jeton fourni par l’interface GitLab dans le terminal prévu à cet effet ; ne le copiez pas dans un dépôt, une capture d’écran, un fichier de configuration partagé ou la sortie d’un journal. Dans toute procédure conservée, remplacez sa valeur par <JETON_DU_RUNNER>.

Au cours de l’enregistrement, choisissez une description identifiable et des étiquettes qui expriment la capacité réelle du nœud : par exemple, macOS, cible Apple ou équipe propriétaire, selon vos conventions internes. Ces étiquettes doivent permettre au fichier de pipeline de demander explicitement le type de nœud attendu. Elles ne constituent pas un contrôle de sécurité en elles-mêmes ; vérifiez également quels projets peuvent utiliser le runner et qui peut modifier leurs scripts.

Shell executor est-il le bon exécuteur pour GitLab CI sur Mac ? Pour une tâche qui doit s’appuyer sur l’environnement macOS de l’hôte, c’est l’exécuteur documenté dans ce contexte. Il ne doit cependant pas être confondu avec un conteneur isolé. Si vous ne pouvez pas faire confiance au code exécuté ou si les projets ne doivent pas partager un environnement hôte, ne résolvez pas le problème en ajoutant seulement une étiquette : étudiez une architecture d’exécution différente et validez ses limites avant d’y déplacer des tâches.

La différence entre LaunchAgent et LaunchDaemon est essentielle à l’exploitation. GitLab indique que son runner macOS fonctionne comme un LaunchAgent au niveau de l’utilisateur et dépend d’une session utilisateur ouverte ; vous ne devez donc pas le traiter comme un service système indépendant comparable à un LaunchDaemon. La procédure macOS de GitLab est la référence pour installer et démarrer le runner sur la version concernée. Une commande de démarrage réussie ne permet pas, à elle seule, de conclure que le runner survivra à une fermeture de session.

L’ouverture automatique de session peut sembler résoudre la disponibilité après redémarrage, mais elle change le profil de risque du Mac. N’en faites pas une recommandation par défaut : les identifiants de session restent exposés au niveau de la machine et la présence d’une session interactive ne renforce pas l’isolation de Shell. Si votre exploitation ne peut pas justifier et protéger ce choix, exigez plutôt une politique explicite de reprise et un test de disponibilité après redémarrage, ou reportez la mise à disposition du runner.

SECTION 04Étape de première exécution : prouvez que le travail atteint Xcode

Commencez par un pipeline minimal dans un dépôt contrôlé. Demandez explicitement les étiquettes du Mac, affichez le nom du nœud et l’utilisateur d’exécution, puis relevez le chemin des outils et les informations Xcode. Gardez le script court et sans secret ; vous voulez établir le chemin d’exécution avant d’ajouter la signature, les tests ou le traitement d’artefacts.

Voici un exemple à adapter. Remplacez les valeurs entre chevrons par celles de votre projet et ne publiez pas les informations sensibles dans les journaux :

stages:
  - verification

verifier_macos:
  stage: verification
  tags:
    - <ETIQUETTE_MAC>
  script:
    - echo "Nœud : $(hostname)"
    - echo "Compte : $(whoami)"
    - xcode-select -p
    - xcodebuild -version
    - xcodebuild -list -project "<CHEMIN_PROJET>.xcodeproj"

Si votre dépôt utilise un espace de travail plutôt qu’un projet, adaptez la commande à son fichier .xcworkspace. Pour une vraie compilation, précisez le schéma et la destination attendue par votre équipe, puis lancez le travail depuis le chemin du dépôt contrôlé. Ne reprenez pas aveuglément un nom de schéma issu d’un exemple : les noms de projet, d’espace de travail, de schéma et les destinations diffèrent selon le dépôt.

Interprétez les preuves dans cet ordre :

Runner enregistré et en ligne : GitLab voit un runner disponible, mais aucun travail n’a nécessairement été exécuté.
Travail attribué : le pipeline a sélectionné le runner ; vérifiez que les étiquettes et les règles d’accès correspondent à la demande.
Script exécuté : les journaux identifient l’hôte et le compte, et montrent les commandes effectivement lancées.
Xcode confirmé : le chemin et la sortie de version correspondent à la base attendue par le projet.
Construction ou test réussi : le vrai schéma du dépôt a terminé la tâche et a produit les résultats que vous avez décidé de conserver.

GitLab CI utilise-t-il le Xcode attendu ? L’observation de xcode-select -p et de xcodebuild -version dans les journaux du travail constitue une vérification bien plus solide qu’une vérification dans votre session interactive. Complétez-la par une compilation ou un test représentatif : un runner peut être visible et exécuter un script simple sans disposer des dépendances, autorisations ou réglages nécessaires à la tâche finale. Vérifiez aussi le statut de sortie, les journaux de compilation et la présence des artefacts attendus ; ne confondez pas un message de commande avec la réussite de tout le travail.

Pour Xcode CI, ajoutez les tâches progressivement. Validez d’abord le dépôt et la sélection du schéma, puis introduisez les tests, la signature ou l’exportation seulement après avoir défini la frontière des secrets. Cette progression permet de localiser un échec : outil absent, mauvais répertoire, schéma incorrect, accès refusé au trousseau ou problème de signature ne sont pas le même incident et ne se corrigent pas par une modification indistincte du runner.

SECTION 05Avant d’élargir les travaux : examinez les secrets et les résidus

Un travail Shell agit dans le contexte de l’hôte : des scripts peuvent écrire dans des répertoires accessibles au compte, consulter des fichiers laissés par un travail précédent ou tenter d’utiliser les identifiants disponibles. GitLab met en garde contre les limites de sécurité des runners auto-hébergés ; consultez ses recommandations de sécurité pour les runners avant de leur confier des projets supplémentaires. Le nettoyage du répertoire de travail est utile, mais ne transforme pas Shell en environnement isolé.

Examinez séparément les éléments suivants avant d’autoriser des tâches plus sensibles :

Accès au dépôt : vérifiez quels projets et branches peuvent envoyer du travail à ce runner, et si les modifications du pipeline sont soumises à une revue appropriée.
Répertoire de travail : définissez ce qui est conservé entre les tâches et ce qui doit être supprimé. Inspectez réellement les fichiers après un travail, au lieu de vous fier à la seule configuration.
Trousseau : recensez les secrets que le compte d’exécution peut lire et ceux qui doivent lui rester inaccessibles. Confirmez le comportement depuis une tâche CI, pas uniquement depuis une session graphique ouverte par un administrateur.
Certificats et signature : réservez les actifs de signature aux projets qui en ont besoin, contrôlez leur disponibilité pour le compte du runner et définissez le retrait des secrets en cas d’incident.
Partage du nœud : refusez l’usage commun à des dépôts de niveaux de confiance différents tant que vous n’avez pas démontré que les frontières d’accès et la purge conviennent à votre modèle de risque.

Le test initial doit rester sans secret de signature. Ensuite, demandez-vous si le projet exige vraiment la signature pendant la CI, si le runner a besoin de l’accès permanent à un trousseau, et comment révoquer les éléments concernés sans rendre le reste de l’équipe indisponible. Si vous ne pouvez pas répondre clairement, maintenez le runner hors des travaux qui manipulent ces actifs.

Point d’arrêt : n’autorisez pas de code non fiable, de projets sans frontière de confiance claire ou de tâches de signature à privilèges élevés sur un runner Shell partagé par défaut. L’étiquette du runner, son statut en ligne et un répertoire de travail distinct ne constituent pas une isolation de sécurité.

À mesure que le périmètre s’élargit, conservez une procédure de retrait simple : empêcher l’attribution de nouveaux travaux, révoquer ou renouveler les secrets concernés, inspecter les journaux et préserver les éléments nécessaires à l’analyse de l’incident. Cette procédure doit être connue de l’équipe qui exploite le runner ; une machine dont personne ne sait désactiver l’accès n’est pas prête à accueillir une tâche sensible.

SECTION 06À la fin de l’essai : validez la reprise avant la mise en service

Un runner en ligne après l’installation n’est pas encore un nœud CI validé. Il faut également vérifier ce qu’il advient quand la session de l’utilisateur prend fin, quand le Mac redémarre et quand le service du runner est arrêté puis relancé selon la procédure prévue. GitLab Runner macOS dépend d’une session utilisateur dans le modèle documenté ; le comportement après fermeture de session doit donc être testé dans votre propre configuration, et non inféré du seul statut affiché dans GitLab.

Après chaque événement de reprise, contrôlez si le runner réapparaît, s’il accepte une tâche, quel compte exécute le script et si Xcode reste sélectionné. Rejouez le pipeline minimal puis une tâche représentative du projet. Si la session est perdue ou si l’environnement d’outils change, consignez le résultat et interrompez l’activation partagée jusqu’à ce que l’équipe ait choisi une politique de redémarrage et vérifié ses conséquences de sécurité.

GitLab Runner continue-t-il après la fermeture de session ou le redémarrage du Mac ? Ne supposez pas que ce sera le cas : la dépendance documentée à une session ouverte signifie que vous devez effectuer une vérification opérationnelle sur le nœud. Le redémarrage peut aussi révéler une sélection d’outils différente, un trousseau indisponible ou un runner qui semble installé mais ne reçoit aucun travail. L’automatisation de la connexion peut modifier ce comportement, mais elle ne doit être retenue qu’après évaluation explicite de son risque.

Utilisez cette liste avant d’autoriser des projets au-delà du dépôt d’essai :

[ ] Le Mac est réservé à une catégorie de projets dont le niveau de confiance est défini.
[ ] Le compte d’exécution et les droits de dépôt sont documentés et distincts des accès personnels non nécessaires.
[ ] Les journaux du travail identifient le nœud, l’utilisateur, le chemin actif des outils et le Xcode réellement appelé.
[ ] Une tâche représentative du projet réussit et son statut ainsi que ses résultats peuvent être vérifiés.
[ ] Les règles de conservation et de suppression du répertoire de travail ont été testées après l’exécution.
[ ] Les règles d’accès au trousseau, aux certificats et aux secrets sont définies avant d’activer la signature.
[ ] La fermeture de session, le redémarrage et la relance du runner ont été testés séparément.
[ ] Une procédure permet de retirer le runner et de revenir à l’organisation précédente si un contrôle échoue.

Votre décision doit découler des preuves observées, pas du fait que GitLab affiche simplement le runner comme actif. Mise à l’essai convient lorsque les travaux sont limités à des projets contrôlés et que les contrôles de reprise sont en cours. Mise en service est défendable lorsque les travaux réels, les accès, les secrets, les journaux et le scénario de redémarrage répondent aux exigences internes. Arrêt ou changement d’architecture s’impose si la session utilisateur, les capacités d’isolation ou la gestion des actifs de signature ne correspondent pas à ces exigences.

Pour estimer si un Mac distant peut servir à un essai temporaire ou à une capacité CI récurrente, examinez les environnements Mac proposés par MACNOX et vérifiez la tarification et les modalités disponibles avant de choisir. Cette option mérite d’être étudiée si votre configuration actuelle repose sur un poste de développeur partagé, un hôte Linux incapable d’exécuter les outils Apple ou un Mac local dont la disponibilité dépend d’une session ouverte et d’une maintenance manuelle. Elle ne dispense ni de valider la confiance accordée aux pipelines ni de tester Xcode, les secrets et la reprise sur le nœud retenu. Si vous avez besoin d’un environnement temporaire pour vérifier le parcours de déploiement sans acheter immédiatement une machine, comparez-le à votre solution actuelle ; pour une charge lourde et stable exigeant une maîtrise physique de l’hôte, l’achat et l’exploitation d’un Mac dédié peuvent rester plus adaptés.