XcodeGen : configurer une CI sur Mac distant, guide 2026

La CI échoue parce que le projet Xcode n’est pas présent après l’extraction du dépôt ?

La solution rapide : faites générer le projet par XcodeGen depuis une spécification versionnée, puis utilisez les outils Xcode sur le Mac distant pour compiler et tester. Fixez les entrées de la pipeline et validez le flux de travail réel : la génération seule ne prouve pas que votre application fonctionne.

Cet article s’adresse aux développeurs qui maintiennent plusieurs cibles Apple et veulent examiner les réglages du projet dans le dépôt. Il s’adresse aussi aux ingénieurs CI qui doivent relier la génération à la compilation et aux tests. Enfin, il concerne les petites équipes qui souhaitent exécuter leurs validations sans dépendre du poste d’un membre.

Préparation : définir le contrat entre XcodeGen et la CI

XcodeGen décrit un projet Xcode à partir d’une spécification en YAML ou en JSON. La CI utilise ensuite le projet généré et les outils fournis avec Xcode pour construire et tester l’application. Ces rôles sont distincts : XcodeGen produit les fichiers du projet ; il ne remplace ni le compilateur ni l’exécution des tests. La documentation du projet XcodeGen décrit les formats de spécification et la génération.

Avant de modifier la pipeline, repérez dans le dépôt :

• le fichier de spécification, par exemple project.yml, et les fichiers qu’il inclut ;
• les répertoires de sources, de ressources et de tests ;
• les cibles et les schémas de compilation concernés ;
• la méthode de gestion des dépendances : Swift Package Manager, CocoaPods ou une autre procédure déjà documentée ;
• les scripts ou variables d’environnement nécessaires à une compilation représentative.

Définissez ensuite ce que signifie « prêt pour la CI ». Si l’objectif est uniquement d’obtenir un projet généré, vous ne validez pas l’étape qui consomme le plus directement l’environnement Apple. Pour une pipeline utile à l’équipe, l’acceptation doit couvrir la génération, une compilation pertinente et, lorsque le projet en possède, des tests.

Écrivez cette définition dans le dépôt. Par exemple, précisez quelles cibles doivent être générées, quel schéma la CI utilise et quelles commandes sont censées s’exécuter après la génération. Ne choisissez pas de version de Xcode ou de XcodeGen au hasard : confrontez les exigences du projet aux versions disponibles et aux références officielles des outils en ligne de commande Xcode. Les outils xcodebuild et les autres outils de ligne de commande concernés sont distribués avec Xcode ; la documentation d’Apple est la référence pour leur disponibilité et leur usage.

La différence compte lors du diagnostic. Une erreur dans la spécification ne se corrige pas en changeant la destination de compilation. À l’inverse, une génération correcte ne garantit ni la résolution des dépendances ni la réussite des tests sur le Mac de la CI.

Préparation : rendre les entrées explicites et reproductibles

Une pipeline ne peut reproduire que les instructions et les dépendances qui lui sont fournies. Gardez la spécification XcodeGen dans le dépôt, ainsi que les scripts réellement nécessaires pour préparer le projet. Décrivez comment la CI choisit ses outils, installe les dépendances et reçoit les paramètres propres à l’environnement.

Séparez les entrées versionnées des secrets. Les identifiants, certificats privés et jetons ne doivent pas être inscrits dans project.yml, dans un script suivi par Git ou dans les journaux. Passez-les par le mécanisme de secrets de votre système CI, limitez leur accès aux tâches qui en ont besoin et évitez de les afficher lors du diagnostic. Pour un agent auto-hébergé, tenez compte des risques liés à l’exécution de code provenant de dépôts ou de contributions non fiables : la documentation de sécurité des agents auto-hébergés détaille les précautions à prendre.

Si le dépôt utilise CocoaPods, reproduisez la procédure prévue par le projet plutôt que de mettre à jour ses dépendances implicitement pendant chaque compilation. La distinction entre installation et mise à jour est expliquée dans le guide sur pod install et pod update. La même règle s’applique aux autres gestionnaires : suivez les fichiers de verrouillage et les scripts que le dépôt a choisi de maintenir.

Pour les schémas, vérifiez que la configuration sélectionnée par la CI est présente et adaptée au test prévu. Un schéma partagé rend ce choix accessible aux membres de l’équipe et à l’automatisation. Les paramètres de construction et de test se contrôlent dans Xcode ; consultez la documentation Apple sur la personnalisation des schémas de compilation avant de considérer un réglage comme implicite.

Génération : produire puis inspecter le projet

Sur le Mac distant, placez-vous dans le répertoire du dépôt et installez ou appelez XcodeGen selon la méthode documentée par le projet. La documentation officielle expose les méthodes d’installation et les commandes disponibles. Dans une pipeline, la commande de génération doit apparaître explicitement dans les étapes exécutées : ne comptez pas sur un fichier Xcode déjà présent dans le répertoire de travail.

Avec une spécification nommée project.yml, la forme documentée est :

xcodegen generate --spec project.yml

Adaptez le nom et le chemin à votre dépôt. Si vous utilisez les dépendances gérées par XcodeGen, vérifiez leur déclaration et leur préparation à partir de la documentation d’usage sur les dépendances. Ne copiez pas une commande d’exemple sans confirmer qu’elle correspond aux options de votre projet.

Après l’exécution, contrôlez le résultat plutôt que le seul code de sortie de la commande :

• le projet apparaît au chemin attendu ;
• les cibles applicatives et de test existent ;
• le schéma demandé par la CI est généré et sélectionnable ;
• les réglages importants correspondent à la plateforme et aux besoins du dépôt ;
• les ressources et sources attendues sont associées aux bonnes cibles.

La FAQ de XcodeGen aborde des questions de comportement et de gestion des fichiers générés. Elle ne permet toutefois pas de conclure que votre projet particulier est bien configuré : ce point exige de contrôler le résultat et de le passer dans la suite de compilation du dépôt.

Attention : « XcodeGen a terminé sans erreur » signifie que la commande de génération a abouti. Cela ne confirme pas que chaque cible, ressource, dépendance ou réglage produit correspond à ce que l’application exige.

Compilation : connecter le projet généré à xcodebuild

Une fois le projet généré, la CI doit sélectionner le bon type d’entrée : un projet .xcodeproj ou, si la configuration du dépôt le demande, un espace de travail .xcworkspace. Indiquez ensuite le schéma et la destination adaptés à la tâche. La référence Apple explique les commandes de construction et les options de xcodebuild dans son guide des commandes de compilation Xcode.

Un exemple indicatif pour un projet et un schéma nommés dans votre dépôt :

xcodebuild -project MonApp.xcodeproj -scheme MonApp build

Cet exemple n’est pas une configuration universelle. Remplacez les noms et ajoutez les paramètres nécessaires à votre projet ; si la CI doit passer par un espace de travail, sélectionnez-le plutôt que le projet. Pour les tests, ajoutez une destination cohérente avec vos cibles et votre environnement, puis utilisez l’action prévue par xcodebuild. Vérifiez les options dans la référence de commande Apple avant d’intégrer une commande à votre script.

L’ordre des opérations doit être lisible dans les journaux :

• récupération propre du dépôt ;
• installation de XcodeGen et préparation des dépendances ;
• génération du projet ;
• compilation du projet ou de l’espace de travail ;
• exécution des tests prévus.

Si un échec survient, cette séparation vous aide à déterminer l’étape concernée. Ne regroupez pas silencieusement installation, génération et compilation dans un script qui n’expose qu’un message d’erreur général.

Pour CocoaPods, vérifiez que la procédure produit et sélectionne l’espace de travail attendu avant d’appeler xcodebuild. Pour Swift Package Manager ou d’autres mécanismes, appliquez les consignes présentes dans le dépôt et confirmez que la CI utilise la même configuration que les développeurs. Les tests automatisés font partie de l’acceptation : le guide Apple sur l’automatisation des tests avec Xcode décrit les principes à prendre en compte.

Cas concret : votre équipe maintient une application et une cible de tests, mais les fichiers du projet changent parfois après une modification de la spécification. Dans ce cas, la pipeline doit générer le projet avant de sélectionner le schéma de test. Si elle compile un fichier de projet conservé d’un ancien état, elle peut valider une configuration différente de celle examinée dans la revue de code.

Validation : décider du sort des fichiers générés

Le choix de commettre ou non le projet généré dans Git relève de la stratégie du dépôt, pas d’une règle universelle. XcodeGen permet de décrire le projet dans une spécification, mais l’équipe doit décider comment cette source et les fichiers générés s’articulent avec ses outils, ses contributions et ses procédures de compilation. La FAQ de XcodeGen sur les fichiers générés fournit des éléments de contexte ; confrontez-les à votre propre flux de travail.

Fichiers générés non suivis : ce choix peut convenir si la spécification versionnée et les dépendances suffisent à recréer un projet correct sur chaque poste et dans la CI. Il évite de maintenir deux représentations concurrentes, mais impose de lancer la génération avant les outils qui attendent le projet.

Fichiers générés suivis : cette approche peut être justifiée si un processus de l’équipe ou un outil aval dépend de leur présence dans le dépôt. Elle implique de vérifier que les différences produites restent prévisibles et que les modifications manuelles ne sont pas écrasées sans examen.

Dans les deux cas, documentez la règle dans le dépôt. Effectuez ensuite une validation depuis un répertoire propre : extrayez le code, préparez les dépendances, générez le projet, lancez une compilation représentative et exécutez les tests retenus. Observez les fichiers modifiés après la génération. Si les différences changent sans modification explicable de la spécification ou des outils, la pipeline n’est pas encore suffisamment maîtrisée.

Cette vérification est aussi l’occasion de tester la qualité des journaux. Une personne qui n’a pas écrit le script doit pouvoir reconnaître si l’échec vient de la spécification, de l’installation d’une dépendance, de la sélection du schéma ou de la compilation. Si les temps de compilation deviennent un enjeu, Apple documente des moyens d’examiner les compilations incrémentielles ; mesurez votre propre pipeline avant de modifier son organisation.

Liste de contrôle avant intégration

• [ ] La spécification XcodeGen et les scripts nécessaires sont suivis dans le dépôt.
• [ ] La CI indique explicitement comment elle obtient XcodeGen et prépare les dépendances.
• [ ] La génération s’exécute depuis un répertoire de travail propre.
• [ ] Le projet produit contient les cibles et le schéma attendus.
• [ ] La commande de compilation sélectionne le bon projet ou espace de travail.
• [ ] Les tests représentatifs s’exécutent après la génération.
• [ ] Les secrets ne sont ni commis dans Git ni imprimés dans les journaux.
• [ ] La politique de suivi des fichiers générés est écrite et vérifiée en CI.
• [ ] Une personne de l’équipe peut localiser l’étape en échec à partir des journaux.

Exploitation : suivre les entrées et les échecs

Une pipeline durable rend visibles les éléments qui peuvent changer son résultat : spécification, version de XcodeGen, version de Xcode choisie pour le projet, méthode d’installation des dépendances et commandes exécutées. Enregistrez ces informations dans la revue de code ou les journaux de CI sans y exposer de secrets.

Quand une mise à jour de spécification ou d’outil est proposée, vérifiez son effet dans une exécution complète plutôt que de ne tester que la génération. Comparez les fichiers produits, examinez les différences et lancez au moins la compilation et les tests qui représentent votre flux de travail. En cas d’échec, conservez les sorties de l’étape concernée pour permettre une reproduction sur le Mac utilisé par la CI.

Choisissez la suite selon le résultat :

• Si la génération, la compilation et les tests passent depuis un dépôt propre, intégrez les commandes dans la pipeline permanente et gardez la règle de versionnement visible.
• Si la génération réussit mais que la compilation échoue, examinez d’abord le schéma, les dépendances et les paramètres sélectionnés par xcodebuild.
• Si des fichiers changent de façon inattendue, comparez la spécification et les versions d’outils avant de décider de commettre le résultat.
• Si des contributeurs ou outils ont besoin du projet déjà présent, réévaluez la politique de suivi plutôt que de masquer la génération dans un script local.

Pour cadrer le poste distant, consultez la page d’assistance Mac et la FAQ sur l’accès et l’utilisation. Elles peuvent aider à clarifier les modalités d’utilisation, mais elles ne remplacent pas la vérification de votre pipeline sur le dépôt réel.

FAQ sur l’intégration de XcodeGen

Comment intégrer XcodeGen à une CI sur Mac distant ?

Versionnez la spécification du projet et les étapes d’installation des dépendances, puis faites exécuter explicitement la génération par la CI avant toute commande de compilation. Le Mac distant fournit l’environnement Xcode et ses outils en ligne de commande. Enregistrez séparément les journaux de génération, de compilation et de tests afin de distinguer une erreur de configuration d’un échec de compilation.

Comment générer le projet Xcode depuis project.yml pendant la CI ?

Dans le répertoire de travail du dépôt, appelez XcodeGen en lui indiquant le fichier de spécification, par exemple avec la commande documentée xcodegen generate --spec project.yml. Vérifiez ensuite le chemin de sortie, les cibles et les schémas attendus. Une commande réussie confirme la génération, mais pas que le projet produit correspond aux exigences de compilation.

Comment vérifier qu’un projet iOS généré se compile et passe les tests ?

Partez d’un dépôt fraîchement extrait, générez le projet, installez les dépendances prévues par le dépôt, puis sélectionnez explicitement le projet ou l’espace de travail, le schéma et la destination avec xcodebuild. Lancez une compilation représentative et les tests associés. Conservez les journaux et vérifiez aussi que la génération ne produit pas de différences inattendues.

Faut-il versionner le projet généré par XcodeGen ?

Ce choix dépend des règles du dépôt et du flux de travail de l’équipe. Si la spécification versionnée permet de recréer le projet de façon fiable et que tous les contributeurs exécutent la génération au bon moment, le projet produit peut être exclu. Si certains outils ou processus attendent sa présence, son suivi peut être justifié. Documentez la règle et vérifiez les différences en CI.

Si votre chaîne actuelle repose sur un poste personnel, vous devez gérer sa disponibilité, les écarts de configuration et les interventions manuelles lorsque la compilation échoue. Un serveur Linux ne fournit pas, à lui seul, l’environnement Xcode requis par ce flux ; acheter un Mac dédié apporte du contrôle, mais immobilise du matériel même lorsque les besoins de test varient. Pour des campagnes de validation, une migration ou une charge temporaire, louer un Mac avec osxmesh peut donc être plus adapté qu’un achat immédiat, à condition de vérifier que l’accès et la durée correspondent à votre pipeline. Consultez les formules de location Mac, puis reproduisez votre génération et vos tests avant de généraliser le changement.

Questions fréquentes