GitHub Actions macOS Runner 2026 : comment configurer un Mac distant ?
GitHub avertit qu’un workflow provenant d’une demande de fusion externe dans un dépôt public peut exécuter du code non fiable sur un runner auto-hébergé, avec un risque pour la machine et ses secrets (consignes de sécurité de GitHub). La décision est donc simple : si le workflow exige Xcode ou macOS et que ses déclencheurs sont réservés à du code de confiance, un Mac distant peut devenir un runner GitHub Actions utile ; limitez d’abord les accès, puis installez le service et vérifiez le tout avec un vrai projet. N’y dirigez pas de tâches exposées à des contributions publiques non fiables avec des justificatifs sensibles.
Ce guide s’adresse aux développeurs iOS qui utilisent GitHub Actions et doivent compiler dans macOS, aux petites équipes qui veulent vérifier leurs accès et leurs journaux de build, ainsi qu’aux personnes disposant déjà d’un Mac distant qu’elles envisagent d’intégrer à leur processus.
Préparation de la machine et choix de périmètre
Avant de télécharger un runner, établissez ce qu’il devra compiler, qui peut déclencher le workflow et quelles informations sensibles le processus pourra utiliser. Un runner auto-hébergé n’est pas seulement une machine de compilation : il exécute les tâches que les workflows autorisés lui envoient et peut accéder à son environnement local. Les recommandations de GitHub sur les runners auto-hébergés insistent notamment sur les implications de sécurité et sur la différence entre une machine contrôlée par l’équipe et un environnement géré.
Le périmètre d’enregistrement détermine qui peut organiser l’accès au runner. L’enregistrement au niveau d’un dépôt convient lorsqu’une seule base de code doit utiliser la machine. Un périmètre d’organisation ou d’entreprise peut être pertinent quand plusieurs dépôts partagent une infrastructure, mais il demande une gouvernance plus large : les administrateurs doivent décider quels dépôts peuvent utiliser le runner et examiner les workflows qui lui sont adressés. Consultez les règles de gestion des accès aux runners avant de retenir un périmètre commun.
| Choix de périmètre | À retenir si… | Point de contrôle avant l’enregistrement |
|---|---|---|
| Dépôt | Le runner ne doit servir qu’un projet et son équipe dispose déjà des droits nécessaires. | Vérifier les personnes autorisées à modifier les workflows et à lancer les tâches. |
| Organisation | Plusieurs dépôts de la même organisation ont besoin du même environnement macOS. | Définir les dépôts autorisés et vérifier que leurs workflows respectent les mêmes règles de confiance. |
| Entreprise | L’administration des runners doit être centralisée à l’échelle de l’entreprise. | Confirmer avec les administrateurs le périmètre de partage et les règles d’accès applicables. |
Un dépôt public peut-il utiliser un runner macOS auto-hébergé ? Techniquement, l’enregistrement d’un runner et sa sélection dans un workflow ne suffisent pas à rendre le scénario sûr. Si des demandes de fusion peuvent provenir de personnes externes, leurs workflows sont susceptibles d’exécuter du code que l’équipe ne contrôle pas. Évitez donc de rendre accessible à ces tâches un runner contenant des secrets, des certificats ou des données locales sensibles. Pour un dépôt public, privilégiez un environnement isolé ou limitez strictement les événements et les autorisations qui peuvent atteindre le Mac.
Avant de poursuivre, utilisez ces conditions de décision :
- Si seuls des changements de branches contrôlées déclenchent des builds et que les personnes autorisées sont clairement identifiées, préparez l’enregistrement du runner.
- Si le dépôt accepte des contributions externes, mais que les workflows de ces contributions ne peuvent pas accéder au Mac, vérifiez cette séparation avec des essais contrôlés avant d’ajouter des secrets.
- Si le code non fiable peut lancer une tâche sur la machine, ou si son chemin d’exécution reste incertain, n’y installez pas de justificatifs sensibles ; revenez à un runner séparé ou à un processus qui n’expose pas le Mac à ces événements.
Vérification de macOS et de Xcode
Le runner doit rester joignable depuis GitHub et pouvoir accéder aux ressources nécessaires à la compilation. Vérifiez d’abord que la session administratrice sur le Mac fonctionne, que la connexion réseau permet le dialogue avec les services requis et que le compte choisi peut lancer les outils du projet. Ces vérifications ne garantissent pas à elles seules qu’un workflow réussira, mais elles évitent de confondre une panne réseau ou un problème de permissions avec un défaut du fichier YAML.
Xcode doit être installé sur la machine si le projet utilise ses outils ou ses SDK. Pour vérifier quels outils de développement sont sélectionnés, ouvrez Terminal et exécutez :
xcode-select -p
Cette commande indique le répertoire de développement actuellement actif. Si la sortie ne correspond pas à l’installation attendue, sélectionnez le bon répertoire avec la commande prévue à cet effet, en remplaçant le chemin d’exemple par celui de la machine :
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
La sélection des outils et leur configuration sont décrites dans la documentation d’Apple sur les réglages des outils de ligne de commande. Apple précise également les modalités d’installation des outils de ligne de commande. Pour un projet qui nécessite Xcode, vérifiez que l’application attendue est installée et que ses composants nécessaires sont disponibles : la seule présence de commandes de développement ne prouve pas que le projet possède les SDK ou les simulateurs dont il a besoin.
Le runner auto-hébergé peut-il lancer un build Xcode ? Oui, si Xcode et l’environnement requis par le projet sont installés sur le Mac, si le runner peut accéder au dépôt et si la tâche est adressée à ce runner. Avant l’enregistrement, exécutez une vérification locale minimale :
xcodebuild -version
xcodebuild -list -project "Chemin/Projet.xcodeproj"
Pour un espace de travail, adaptez la commande à son fichier :
xcodebuild -list -workspace "Chemin/Projet.xcworkspace"
Ces appels permettent de repérer les problèmes de sélection des outils et de confirmer que Xcode reconnaît le projet ainsi que ses schémas. Ils ne valident pas encore la compilation : celle-ci dépend aussi des dépendances, de la configuration de build et des destinations définies par le projet. Gardez ces éléments identiques entre le test local initial et le premier workflow distant, afin de pouvoir attribuer les échecs à une cause précise.
Enregistrement du runner
Créez le runner depuis les paramètres du périmètre retenu : dépôt, organisation ou entreprise. Suivez les consignes affichées pour choisir macOS et télécharger l’application du runner. L’interface fournit les instructions adaptées au contexte d’enregistrement ; utilisez-les plutôt qu’une archive ou une procédure copiée depuis une autre installation. Les instructions officielles pour ajouter un runner indiquent comment démarrer cette configuration et soulignent les risques associés au code non fiable.
Dans le répertoire de travail choisi sur le Mac, décompressez l’application du runner, puis lancez la configuration avec la commande affichée dans l’interface. Le flux demande des informations liées à l’enregistrement et peut proposer des étiquettes. Ne copiez pas un jeton dans un article, un ticket public, une capture d’écran ou un dépôt. Traitez-le comme une information d’accès temporaire : saisissez-le dans la session prévue et ne le conservez pas dans un script partagé.
Pendant la configuration :
- Attribuez un nom reconnaissable au runner afin que l’équipe puisse l’identifier dans les paramètres.
- Conservez les étiquettes correspondant au système et à l’architecture indiqués par l’application ; n’ajoutez une étiquette propre à l’équipe que si les workflows en ont réellement besoin.
- Choisissez un répertoire de travail adapté à l’espace disponible et aux règles de conservation des fichiers du projet.
- Confirmez que l’enregistrement concerne le périmètre attendu, puis vérifiez que le runner apparaît en ligne dans les paramètres GitHub.
Une connexion réussie à cette étape prouve que le runner communique avec GitHub, mais pas que le projet peut compiler. Si le runner reste hors ligne, ne contournez pas le problème en ouvrant des accès plus larges sans diagnostic. Vérifiez d’abord l’état du processus, la connectivité et les messages de configuration. L’aide de GitHub pour surveiller et dépanner les runners fournit des points de contrôle utiles pour isoler ces incidents.
Maintien du service après la configuration
Lancer le runner dans une fenêtre Terminal suffit pour vérifier une première connexion, mais ne garantit pas qu’il reprendra automatiquement son activité après une fermeture de session ou un redémarrage du Mac. Si le runner doit recevoir des tâches sans qu’une personne ouvre Terminal, configurez le service macOS selon le parcours officiel de configuration de l’application et de son service. La documentation décrit les commandes à utiliser pour installer, démarrer et contrôler le service ; adaptez-les à la version de l’application présente sur la machine.
Après l’installation, vérifiez séparément l’état du service sur le Mac et l’état en ligne affiché dans les paramètres. Un service marqué comme démarré ne garantit pas que le runner termine correctement son enregistrement auprès de GitHub ; inversement, un runner visible en ligne ne prouve pas que le contexte de session conviendra aux tâches de compilation.
Cette distinction est importante pour les projets qui utilisent une trousseau de clés, des certificats, des outils demandant une interaction graphique ou des configurations préparées dans le compte d’un développeur. Une tâche lancée en arrière-plan ne doit pas être présumée capable de retrouver automatiquement les mêmes éléments qu’une session de bureau ouverte. Testez le contexte réel du service avec un build simple avant de lui confier une opération qui dépend d’un trousseau, d’une invite de sécurité ou d’une fenêtre d’application.
Comment conserver le runner en ligne sur un Mac distant ? Configurez-le comme service macOS selon les instructions officielles, puis vérifiez son état après un redémarrage ou un arrêt contrôlé du service. Si le runner ne revient pas en ligne, examinez les journaux et la configuration avant de considérer le Mac comme disponible pour les tâches automatisées. Un lancement manuel dans une session ouverte peut servir de diagnostic, mais ce n’est pas une preuve de fonctionnement sans intervention.
La documentation de KuzCloud peut aider à vérifier les modalités d’accès au Mac distant, sans remplacer le diagnostic des états du service et du runner. Ne supposez pas non plus que les réglages de session graphique, les clés de signature ou les fichiers temporaires sont conservés d’une exécution à l’autre : établissez explicitement la manière dont le projet les fournit, les protège et les retire.
Premier workflow et construction Xcode
Une fois le runner enregistré et son service vérifié, créez un workflow minimal dans le dépôt. L’objectif de ce premier essai est de confirmer la sélection du runner, l’accès au code et l’appel de Xcode, pas de déployer immédiatement l’application. La syntaxe de configuration des workflows GitHub Actions définit notamment les permissions et les étapes du travail.
Voici une structure de départ à adapter au nom du schéma et au chemin du projet :
name: Build iOS
on:
push:
branches:
- main
permissions:
contents: read
jobs:
build:
runs-on: [self-hosted, macOS]
steps:
- name: Checkout du dépôt
uses: actions/checkout@v4
- name: Vérifier les outils
run: |
xcode-select -p
xcodebuild -version
- name: Compiler le projet
run: |
xcodebuild \
-project "Chemin/Projet.xcodeproj" \
-scheme "NomDuScheme" \
-sdk iphonesimulator \
-configuration Debug \
build
Dans cet exemple, les étiquettes self-hosted et macOS orientent le travail vers un runner auto-hébergé macOS. Les étiquettes disponibles doivent correspondre à celles enregistrées sur le runner ; si l’équipe utilise une étiquette supplémentaire pour distinguer ses machines, vérifiez sa présence des deux côtés avant de l’ajouter à runs-on. Les instructions de GitHub sur l’utilisation d’un runner dans un workflow détaillent cette sélection.
Le déclencheur de l’exemple est volontairement limité à une branche de confiance. Adaptez-le à votre processus, mais ne l’élargissez pas avant d’avoir vérifié les droits qui accompagnent chaque type de déclenchement. La permission contents: read correspond à une tâche de lecture du dépôt ; si le workflow doit écrire ou accéder à d’autres ressources, n’ajoutez que les permissions nécessaires et examinez les conséquences. Une étape de compilation n’a généralement pas besoin de secrets destinés à la signature ou à la publication.
Lancez ensuite le workflow depuis la branche autorisée et observez les journaux. Vérifiez que le travail est bien affecté au runner attendu, que le dépôt est récupéré, que les commandes de diagnostic renvoient les outils voulus et que la compilation aboutit. Lorsque le projet nécessite des dépendances ou une destination de compilation particulière, ajoutez-les séparément, puis répétez le test. Cela rend les erreurs plus faciles à attribuer : environnement Xcode, configuration du projet, résolution des dépendances ou permissions du workflow.
Cette étape porte sur le build, pas sur l’archivage signé ni sur la publication. Ces opérations ajoutent des exigences de signature, de stockage des certificats et de protection des secrets qui doivent faire l’objet d’une validation distincte. Pour les informations de compte et les justificatifs employés sur une machine distante, consultez également les engagements de confidentialité et limitez leur présence sur le runner au strict nécessaire.
Acceptation, maintenance et retrait
N’intégrez pas immédiatement le runner à un processus de livraison parce qu’un build isolé a réussi. Rassemblez des preuves qui montrent que l’installation fonctionne dans les conditions attendues et que l’équipe saura réagir à une interruption. La liste suivante peut être cochée lors de la recette :
- [ ] Le runner apparaît en ligne dans le périmètre GitHub prévu.
- [ ] Le workflow de test est dirigé vers le runner attendu, et non vers une machine différente.
- [ ] Le dépôt est récupéré et les journaux montrent les commandes Xcode exécutées.
- [ ] Le résultat de build correspond aux attentes du projet et peut être vérifié par l’équipe.
- [ ] L’arrêt puis le redémarrage contrôlés du service permettent au runner de revenir en ligne.
- [ ] Les déclencheurs et les permissions du workflow sont limités aux usages nécessaires.
- [ ] Aucun secret ou certificat de publication n’est utilisé par le workflow de validation si cela n’est pas indispensable.
La validation du résultat dépend du projet : un build réussi ne prouve pas à lui seul qu’une application est prête à être distribuée. Comparez le produit généré aux critères internes, conservez les journaux nécessaires au diagnostic et déterminez où les fichiers de build doivent être stockés ou supprimés. Le runner est une machine persistante, contrairement à un environnement dont l’équipe peut supposer qu’il sera recréé proprement après chaque tâche ; prévoyez donc la suppression des fichiers temporaires, la gestion des caches et l’examen des processus laissés en arrière-plan.
Pour l’exploitation courante, attribuez la responsabilité des mises à jour du runner et de Xcode, prévoyez une vérification après modification de l’environnement et réexaminez les accès lorsque l’équipe ou le dépôt change. En cas d’échec, comparez l’état en ligne, les journaux de la tâche, les messages du service et le résultat de la même commande lancée localement. Cette comparaison permet de séparer un problème d’ordonnancement d’un problème de dépendance ou de projet. Les consignes de surveillance de GitHub couvrent aussi les vérifications à effectuer lorsqu’un runner ne prend pas en charge une tâche.
Prévoyez enfin une procédure de retrait : arrêter le service, désenregistrer le runner selon les instructions de GitHub, supprimer les fichiers de travail qui ne doivent pas rester sur le Mac et révoquer ou remplacer les justificatifs auxquels il a eu accès. Retirez aussi les étiquettes ou références de workflow devenues inutiles. Un runner oublié, encore inscrit dans un périmètre partagé, complique l’audit et peut attirer des tâches qu’aucun responsable ne surveille.
Si les builds sont lancés depuis le Mac personnel d’un développeur, la disponibilité dépend de son usage quotidien, l’environnement peut changer au gré de ses projets et les tâches d’automatisation risquent d’interférer avec sa session de travail. Un environnement hébergé réduit cette dépendance au matériel local, mais ne donne pas nécessairement la maîtrise d’une machine macOS persistante avec les outils et réglages propres au projet. Lorsque le besoin est un environnement Xcode disponible à distance pour exécuter des workflows de confiance, la location d’un Mac distant peut donc être une option à évaluer ; elle ne dispense ni d’isoler les tâches non fiables ni de gérer soigneusement les certificats. Consultez la présentation de KuzCloud pour vérifier si l’accès proposé correspond à votre mode de travail avant d’y installer un runner.
Passez vos builds iOS sur un Mac distant dédié
Avec KuzCloud, exécutez vos workflows de compilation sur un Mac mini M4 physique, sans ressources partagées ni virtualisation.
Installez Xcode et vos outils CI en toute liberté grâce à l’accès root complet et connectez-vous à distance par SSH ou VNC.