Le déploiement de GitLab Runner sur macOS peut fournir un nœud de compilation durable pour vos projets iOS et macOS, mais l’état « en ligne » ne suffit jamais pour déclarer l’installation terminée. La méthode fiable consiste à utiliser un compte macOS dédié, le Shell executor, une session utilisateur persistante, un environnement Xcode vérifié, puis une validation réelle après redémarrage et avec les tâches de signature isolées.

Cette procédure s’adresse aux développeurs qui remplacent une compilation manuelle par GitLab CI, aux ingénieurs DevOps qui maintiennent une chaîne multiplateforme et aux équipes qui cherchent un Mac distant capable de rester disponible pour les compilations, les tests, l’archivage ou certains traitements audio, vidéo et design.

Phase Décision à prendre Preuve attendue
Préparation Confirmer que la tâche dépend réellement de macOS Xcode, SDK Apple, simulateur ou signature requis
Installation Créer un compte CI et enregistrer le Runner Runner visible avec un tag dédié
Persistance Vérifier la session macOS et le LaunchAgent Retour après déconnexion SSH et redémarrage
Première pipeline Construire puis tester sans signature Journaux et code retour conservés
Production Ajouter les certificats avec des limites strictes Secrets absents du dépôt et des branches non fiables
01

Le périmètre du Runner macOS

Un Runner macOS est pertinent lorsque la tâche utilise des composants Apple qui ne sont pas disponibles dans un environnement Linux classique. La compilation Xcode, l’utilisation d’un SDK iOS, les tests sur simulateur, l’archivage et la signature d’une application entrent dans cette catégorie.

En revanche, une étape de lint, de génération de documentation, de compilation d’un service web ou de création d’images de conteneurs peut souvent rester sur Linux. Cette séparation réduit l’exposition du Mac et évite de réserver une machine Apple à des tâches qui ne l’exigent pas.

Avant toute installation, définissez la portée du Runner :

  • Projet : le choix le plus simple pour commencer avec un dépôt clairement identifié.
  • Groupe : adapté à plusieurs projets qui partagent la même chaîne Xcode et le même niveau de confiance.
  • Runner partagé : déconseillé pour les pipelines qui manipulent des certificats, des clés privées ou des profils de distribution.

Le Shell executor lance les commandes directement sur la machine. Il ne fournit donc pas la même isolation qu’un environnement éphémère. Un script de pipeline peut accéder aux fichiers disponibles pour le compte du Runner, modifier son environnement et exploiter les permissions accordées à ce compte. La documentation officielle sur le Shell executor doit être lue avant d’autoriser des dépôts externes ou des branches dont le contenu n’est pas contrôlé.

Votre condition de sortie est la suivante : vous devez savoir quels dépôts ont le droit d’exécuter du code sur le Mac, quelles branches peuvent utiliser des secrets et qui est responsable du nettoyage du workspace.

02

Le compte CI et l’inscription du Runner

Créez un compte macOS distinct du compte personnel du développeur. Ce compte doit disposer des outils nécessaires à la compilation, mais il ne doit pas hériter automatiquement de vos clés privées, de vos documents personnels ou de vos sessions de développement.

Connectez-vous d’abord avec ce compte dans une session graphique. Cette étape est importante, car l’environnement utilisateur, le trousseau et certains composants Xcode seront associés à cette session. Vérifiez ensuite l’architecture du Mac et installez le binaire GitLab Runner correspondant à la machine.

La procédure officielle d’installation de GitLab Runner sur macOS décrit les méthodes prises en charge par GitLab et le fonctionnement du service utilisateur. Utilisez les commandes et les paramètres affichés dans la documentation au moment de votre installation, car les mécanismes d’inscription et les options de sécurité peuvent évoluer.

Préparez l’environnement dans cet ordre :

  • ouvrir une session graphique avec le compte CI ;
  • installer GitLab Runner ;
  • installer Xcode et ses composants nécessaires ;
  • vérifier le chemin actif avec xcode-select ;
  • accepter les composants de première exécution avec les commandes adaptées à votre installation ;
  • créer le Runner dans GitLab ;
  • utiliser un tag explicite tel que macos-ios ;
  • tester la communication avant d’ajouter une pipeline de production.

Exemple avec des valeurs fictives :

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.invalid/" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --executor "shell" \
  --description "macos-ci-build" \
  --tag-list "macos-ios"

Le jeton doit rester dans votre gestionnaire de secrets ou dans une variable protégée. Ne le copiez pas dans le dépôt, dans un ticket public ou dans une capture d’écran. La documentation GitLab sur l’inscription des Runners explique les paramètres du processus et les différences entre les anciens jetons d’inscription et les jetons d’authentification.

Élément Choix conseillé Risque principal
Compte d’exécution Compte macOS dédié Environnement à préparer séparément
Exécuteur shell pour une compilation locale Xcode Isolation limitée
Portée initiale Projet Mutualisation plus faible
Étiquette Tag réservé à macOS et iOS Pipeline mal routée si le tag manque
Authentification Jeton protégé Compromission du Runner si le jeton fuit

Ne déduisez pas que l’inscription est réussie parce que le Runner apparaît dans l’interface. À ce stade, vous avez seulement établi une communication avec GitLab. L’accès au trousseau, au simulateur, au workspace et aux dépendances reste à vérifier.

Si vous ne disposez pas encore d’un Mac réservé à cette fonction, examinez d’abord les conditions d’accès, la possibilité de créer un compte CI séparé et la méthode de connexion prévues dans une commande de Mac distant pour le développement. Cette vérification doit précéder l’installation de Xcode : un nœud qui ne permet pas une session durable ou une administration SSH cohérente ne convient pas à une chaîne CI persistante.

03

La persistance de la session macOS

Le principal piège du déploiement de GitLab Runner sur macOS apparaît après la première reconnexion ou le premier redémarrage. Un Mac peut être allumé, accessible en SSH et pourtant présenter un Runner hors ligne. Il peut aussi apparaître disponible tout en étant incapable d’utiliser le trousseau ou la session graphique attendue par Xcode.

GitLab documente le fonctionnement du Runner macOS comme un LaunchAgent associé à l’utilisateur. Le service démarre dans la session de cet utilisateur et s’arrête lorsque cette session se termine. La procédure macOS officielle explique également le rôle des commandes d’installation, de démarrage et d’état.

Après l’installation, vérifiez le comportement avec les commandes adaptées à votre environnement :

cd ~
gitlab-runner install
gitlab-runner start
gitlab-runner status

Le fichier de lancement est placé dans le répertoire LaunchAgents du compte utilisateur. Ne remplacez pas cette méthode par un script communautaire qui transforme le Runner en service système sans avoir vérifié sa compatibilité et ses conséquences. Une modification non prise en charge peut résoudre un redémarrage apparent tout en cassant l’accès au trousseau ou à la session graphique.

Testez successivement :

  • une exécution après connexion graphique normale ;
  • la fermeture de la session SSH ;
  • une interruption réseau temporaire ;
  • une déconnexion puis reconnexion du compte CI ;
  • un redémarrage complet du Mac ;
  • une nouvelle compilation utilisant le même workspace.

Attention : l’état « en ligne » prouve uniquement que le Runner communique avec GitLab. Il ne prouve pas que Xcode utilise le bon répertoire développeur, que le simulateur est disponible ou que le trousseau est déverrouillé.

L’ouverture automatique d’une session peut améliorer la disponibilité, mais elle augmente le risque en cas d’accès physique non maîtrisé. Évaluez le chiffrement du disque, la protection du compte administrateur, le contrôle de la console et la présence de certificats de distribution avant de l’envisager. Pour une machine de publication, la disponibilité ne doit pas être obtenue en exposant inutilement une session contenant des clés privées.

04

La première pipeline GitLab CI avec Xcode

Commencez sans signature. Vous devez d’abord démontrer que le dépôt est récupéré, que les dépendances sont accessibles et que Xcode peut compiler le projet dans le compte utilisé par le Runner.

Exemple de pipeline à adapter :

stages:
  - build
  - test

variables:
  LANG: "en_US.UTF-8"

build_ios:
  stage: build
  tags:
    - macos-ios
  script:
    - xcode-select -p
    - xcodebuild -version
    - xcodebuild -workspace "App.xcworkspace" \
        -scheme "App" \
        -sdk iphonesimulator \
        -configuration Debug \
        -destination 'platform=iOS Simulator,name=CI Simulator' \
        build | tee build.log
  artifacts:
    when: always
    paths:
      - build.log

test_ios:
  stage: test
  tags:
    - macos-ios
  script:
    - xcodebuild test \
        -workspace "App.xcworkspace" \
        -scheme "App" \
        -destination 'platform=iOS Simulator,name=CI Simulator'

Remplacez le workspace, le schéma, la destination et les dépendances par ceux du projet réel. Le nom d’un simulateur, le chemin d’un SDK et les exigences système doivent être contrôlés dans la documentation Apple correspondant à votre version de Xcode.

La documentation GitLab consacrée à la configuration macOS fournit les indications spécifiques à l’utilisation de Xcode avec un Runner. Elle doit compléter la documentation de votre projet, et non la remplacer.

La première pipeline doit fournir des preuves exploitables :

  • le dépôt et ses sous-modules sont récupérés ;
  • xcode-select -p renvoie le chemin attendu ;
  • la compilation retourne un code de sortie valide ;
  • les tests produisent des journaux consultables ;
  • les artefacts sont conservés après un échec ;
  • le répertoire de travail peut être nettoyé sans intervention manuelle.

Pour les projets audio, vidéo ou design, ajoutez une tâche représentative de votre activité. Vous pouvez vérifier l’export d’un fichier audio, la génération d’un paquet de ressources, le rendu d’un projet de démonstration ou le traitement d’un média de test. Une pipeline qui compile uniquement un projet minimal ne permet pas de conclure que le Mac convient à vos charges réelles.

Étape Secret requis Preuve d’acceptation
Récupération du dépôt Non Dépôt accessible avec ses dépendances
Résolution des paquets Généralement non Versions récupérables dans un environnement propre
Build pour simulateur Non Compilation terminée correctement
Tests Selon le projet Rapports et journaux disponibles
Archive de distribution Oui Identités accessibles uniquement au Runner autorisé
05

Les certificats et le trousseau

Ajoutez la signature seulement après la réussite du build sans signature. Cette progression sépare les problèmes liés à Xcode de ceux liés aux identités Apple, aux profils et au trousseau.

Une identité de signature ne se limite pas à un certificat public. La clé privée correspondante est nécessaire pour signer. La note Apple Inside Code Signing: Certificates explique le rôle des certificats, des clés privées et du trousseau macOS.

Pour un Runner distant, utilisez un trousseau dédié au compte CI lorsque votre méthode de publication le permet. Protégez son mot de passe et les éventuels fichiers .p12. Ne placez pas ces fichiers dans le dépôt et ne les rendez pas accessibles aux pipelines provenant de forks ou de branches non approuvées.

Les protections à mettre en place sont les suivantes :

  • variables GitLab protégées et masquées ;
  • Runner de publication réservé aux projets de confiance ;
  • branches de publication protégées ;
  • absence de secrets dans les logs ;
  • suppression des fichiers temporaires après l’archive ;
  • rotation documentée des certificats ;
  • procédure de révocation en cas d’exposition ;
  • séparation entre les tâches de test et de distribution lorsque le risque le justifie.

La documentation Apple sur le partage des identités de signature rappelle que les éléments de signature doivent être gérés comme des actifs sensibles. Le certificat public ne doit pas être confondu avec la clé privée, qui mérite une protection renforcée.

Vérifiez également les réglages de build utilisés par le projet. Les paramètres CODE_SIGN_IDENTITY, CODE_SIGN_STYLE, l’équipe Apple, le profil de provisionnement et le chemin du trousseau doivent correspondre à la méthode retenue. La référence Apple des réglages de build Xcode permet de confirmer le comportement des paramètres plutôt que de copier une configuration trouvée dans un ancien projet.

Si vous utilisez la signature automatique, le compte connecté et les services Apple deviennent des dépendances de la pipeline. Si vous utilisez une signature manuelle, vous devez gérer explicitement le certificat, la clé privée, le profil et les droits d’accès. Dans les deux cas, conservez une procédure de renouvellement indépendante du poste d’un développeur.

06

La validation opérationnelle du nœud

La mise en production doit reposer sur une tâche réelle. Un projet vide peut confirmer l’installation du binaire, mais il ne révèle pas les problèmes de dépendances, de cache, de workspace ou de signature.

Faites passer une pipeline représentative du projet et observez :

  • le temps passé en attente ;
  • la réussite de la compilation ;
  • la réussite des tests ;
  • la production des artefacts ;
  • la croissance du workspace ;
  • l’efficacité du cache ;
  • les conflits entre tâches ;
  • le comportement après redémarrage ;
  • l’état du trousseau durant une publication.
Contrôle Résultat attendu Décision si le contrôle échoue
Redémarrage Le Runner revient avec le compte CI Revoir la session et le LaunchAgent
Build réel Le schéma du projet termine correctement Corriger Xcode, les dépendances ou les variables
Tests Les rapports restent accessibles Revoir le simulateur et les destinations
Signature L’archive est produite sans secret exposé Revoir le trousseau et les branches autorisées
Nettoyage Les anciens workspaces ne s’accumulent pas Ajouter une politique de nettoyage
Concurrence Les tâches ne partagent pas un état mutable Limiter la concurrence ou isoler les répertoires

Si le Runner reste hors ligne après redémarrage, ne le réinscrivez pas immédiatement. Vérifiez d’abord la session graphique, le chargement du LaunchAgent, les permissions du compte et la présence du fichier de configuration. Si le Runner est en ligne mais que la publication échoue, examinez le trousseau et les droits de la clé privée avant de modifier la pipeline.

La maintenance doit avoir un responsable identifié. Elle comprend la mise à jour de macOS, de Xcode et de GitLab Runner, la surveillance de l’espace disque, la rotation des certificats, la vérification des journaux, le nettoyage des caches et le test périodique de reprise.

Les commandes de gestion telles que start, stop, restart et status sont décrites dans la référence officielle des commandes GitLab Runner. Ajoutez ces contrôles à votre documentation interne, mais ne considérez pas le statut du service comme une preuve suffisante de bon fonctionnement.

07

Questions fréquentes

GitLab Runner peut-il rester disponible sur un Mac distant ?

Oui, à condition que le compte CI dispose d’une session macOS persistante et que le Runner soit installé selon le mode de service pris en charge. Une machine joignable en SSH ne garantit pas la disponibilité du service utilisateur. Testez la reconnexion, le redémarrage, le trousseau et une vraie compilation avant d’autoriser les pipelines de production.

Pourquoi le Runner macOS est-il hors ligne après un redémarrage ?

La cause est souvent liée à l’absence de session graphique du compte qui exécute le Runner. Le service macOS s’appuie sur un LaunchAgent utilisateur et non sur un démon système comparable à ceux utilisés sur Linux. Vérifiez la connexion du compte CI, le chargement de l’agent, les permissions et le fichier de configuration avant de modifier l’architecture.

Comment une pipeline GitLab CI appelle-t-elle Xcode ?

Le job doit être envoyé vers un Runner portant un tag macOS, puis appeler xcodebuild avec le workspace, le schéma, le SDK et la destination appropriés. Commencez par un build sans signature, ajoutez les tests, puis introduisez l’archive. Cette séparation permet de distinguer un problème de projet d’un problème de certificat ou de trousseau.

Quelle méthode utiliser pour les certificats d’un Runner distant ?

Réservez les certificats aux branches et projets de confiance, stockez les données sensibles dans des variables protégées et utilisez un trousseau accessible au compte CI. Ne placez jamais une clé privée dans le dépôt. Un Runner qui accepte du code provenant de forks ne doit pas avoir accès aux actifs de publication.

Quels contrôles précèdent la mise en production ?

Vérifiez une pipeline réelle, la récupération des dépendances, la compilation, les tests, les artefacts, la signature si elle est nécessaire, le nettoyage du workspace et la reprise après redémarrage. Un Runner affiché comme disponible mais incapable de restaurer sa session ou d’accéder au trousseau reste un nœud de préproduction.

Le déploiement de GitLab Runner sur macOS devient donc une bonne solution lorsque vous avez besoin d’un Mac disponible pour des compilations Apple, mais que vous ne voulez pas immobiliser le poste personnel d’un développeur. Un Mac local peut être indisponible pendant les congés, subir une mise à jour non planifiée, dépendre d’une connexion résidentielle ou perdre sa session après un redémarrage. Si vos builds sont temporaires ou liés à un calendrier de publication variable, un Mac distant loué par VpsMesh peut être plus flexible qu’un achat de matériel qui reste inutilisé entre deux versions. Consultez les tarifs de location de Mac mini après avoir confirmé les exigences du compte CI, de la session graphique, de l’accès SSH et de votre chaîne Xcode.