Échec d’export IPA avec fastlane gym : que faire ? 2026

La documentation de fastlane gym distingue deux réglages d’export : export_method et export_options. Si votre IPA n’est pas créé, ne modifiez pas ces paramètres avant d’avoir repéré la première erreur utile dans les journaux : séparez l’échec de compilation ou d’Archive de celui de l’export, puis vérifiez la distribution et la signature réellement visées. Cette semaine, commencez par enregistrer le journal complet d’une exécution et comparez-le à une exécution qui fonctionne, si vous en avez une.

Ce guide s’adresse aux développeurs indépendants et aux petites équipes qui utilisent fastlane pour construire une app iOS, mais ne savent pas à quelle étape gym s’arrête. Il est également utile si vous maintenez un Mac distant ou un environnement d’intégration continue, ou si vous devez produire des IPA pour plusieurs modes de distribution.

fastlane gym : repérer l’étape qui échoue

Un message d’erreur final ne suffit pas à déterminer la cause. Dans une exécution, distinguez la compilation, la création de l’Archive, l’export de cette Archive vers un IPA et la vérification du fichier résultant. La documentation d’Apple décrit séparément la création d’une Archive et l’export en ligne de commande avec -exportArchive et un fichier d’options d’export. Le processus d’export documenté par Apple permet de comprendre pourquoi une Archive réussie ne prouve pas que l’IPA a été généré.

Dans les journaux de fastlane, cherchez la première erreur qui interrompt réellement le processus, plutôt que la dernière ligne récapitulative. Repérez la commande xcodebuild lancée et vérifiez si elle tente une action d’Archive ou une action d’export. Le libellé final peut seulement indiquer que gym a échoué ; il ne prouve pas, à lui seul, que le problème vient de export_options.

Vous pouvez extraire les lignes utiles d’un journal enregistré ainsi :

grep -nE "error:|ARCHIVE FAILED|EXPORT FAILED|exportArchive" build.log

Cette recherche sert à réduire le volume du journal, pas à établir le diagnostic automatiquement. Une ligne contenant « error » peut appartenir à un avertissement ou à une étape antérieure qui n’a pas arrêté la construction. Revenez au contexte autour de la première erreur bloquante, puis comparez-le à la commande exécutée et au statut de l’action en cours.

Pour éviter de confondre les étapes, notez séparément les résultats suivants : la commande d’Archive a-t-elle abouti ? L’export a-t-il été lancé ? Un IPA a-t-il été créé au chemin attendu ? L’importation ultérieure dans App Store Connect relève d’une autre étape : un refus ou un traitement en attente sur la plateforme ne signifie pas automatiquement que l’export de gym a échoué.

Scheme, projet et compilation : les contrôles avant l’Archive

Si l’Archive ne se termine pas, corriger la méthode d’export est généralement une mauvaise première action : l’export n’a peut-être jamais commencé. Contrôlez d’abord que le lane transmet le bon projet ou le bon espace de travail, ainsi que le Scheme prévu. Un Scheme détermine les actions de construction utilisées pour une cible ; un Scheme différent peut donc lancer une configuration ou une combinaison de cibles qui ne correspond pas à votre version attendue. La documentation Apple sur les Schemes explique leur rôle dans la configuration des actions.

Examinez ensuite la configuration de construction et la destination sélectionnées par votre lane. Vérifiez le nom exact du Scheme, la cible à archiver, la configuration utilisée et les paramètres transmis à gym. Une erreur de résolution des dépendances, un nom de Scheme incorrect ou une compilation qui échoue doit être traitée à son point d’origine. Changer export_method ne peut pas réparer un code qui ne compile pas.

Dans la pratique, confrontez la commande annoncée dans la sortie de fastlane à votre configuration Xcode. Lorsque le projet contient plusieurs cibles, vérifiez également que l’Archive comprend la bonne application et les extensions attendues. Si vous venez de modifier le Scheme, les dépendances ou les réglages de compilation, comparez le journal avec celui de la dernière Archive validée, en évitant de partager des secrets ou des données de signature dans une demande d’aide.

Archive réussie, export IPA en échec : contrôler les paramètres

Lorsque l’Archive est bien produite mais que l’export s’arrête, la question centrale devient la destination du fichier. Une IPA destinée à une distribution par TestFlight ou l’App Store ne suit pas forcément le même chemin de signature qu’une version Ad Hoc. Choisissez donc d’abord l’usage prévu, puis alignez export_method et export_options sur cet objectif. La documentation de gym et de ses paramètres d’export est la référence pour vérifier les options prises en charge par votre version.

Comment vérifier export_method et export_options ?

Lisez les deux réglages ensemble, avec la configuration réellement utilisée par le projet. export_method exprime l’intention de distribution ; export_options transmet les réglages détaillés attendus lors de l’export. Si l’un indique une destination et l’autre des paramètres conçus pour une autre voie, l’Archive peut être valide alors que l’export échoue ou produit un fichier inadapté.

Comparez la configuration du lane à celle d’Xcode pour le même Scheme et le même objectif de distribution. Examinez notamment les options conservées dans un fichier plist, les correspondances entre identifiants de cibles et profils, ainsi que les options de signature. Ne copiez pas aveuglément une valeur depuis un ancien tutoriel : les paramètres disponibles et le comportement d’export peuvent évoluer avec fastlane et Xcode. En cas de doute, vérifiez la documentation correspondant aux outils installés et le détail de la commande xcodebuild affichée dans le journal.

Les documents d’Apple sur la distribution des apps pour les tests et les versions distinguent les objectifs de diffusion. Pour une distribution Ad Hoc, Apple demande un profil associé aux appareils enregistrés prévus pour cette distribution ; le profil doit correspondre à l’app et à sa signature. Les exigences Apple pour créer un profil Ad Hoc vous aident à vérifier ce point. Ne réutilisez donc pas une configuration App Store comme si elle convenait automatiquement à un test Ad Hoc.

Signature et profils : vérifier la cohérence

Une erreur d’export peut venir d’une contradiction entre les réglages d’export, les capacités de l’app, son identifiant et les profils disponibles. Avant de régénérer des certificats, relevez les identifiants des cibles concernées et vérifiez, pour chacune, quel profil est sélectionné ou attendu. Assurez-vous aussi que l’identité de signature est accessible à l’utilisateur qui exécute le lane.

La démarche diffère selon le mode choisi. Avec la signature automatique, vérifiez que Xcode peut résoudre les paramètres nécessaires pour le Scheme et l’équipe concernés. Avec une signature manuelle, contrôlez explicitement que le profil sélectionné correspond à l’identifiant de l’app et à l’usage visé. La documentation fastlane sur la configuration de signature du projet Xcode décrit les réglages à contrôler ; son guide de dépannage des problèmes de signature aide à isoler les erreurs liées aux certificats et aux profils.

Attention : si l’erreur apparaît au moment où fastlane récupère des certificats ou des profils depuis un dépôt privé, vous êtes probablement en amont du problème d’export. Traitez alors l’accès au dépôt et la récupération des éléments de signature séparément ; le guide officiel de fastlane match couvre ce mécanisme.

Dans ce cas, évitez de modifier simultanément les identifiants, le profil, le mode d’export et la configuration du Scheme. Une seule modification à la fois vous permet de savoir si l’erreur vient d’une incompatibilité de signature ou d’un autre réglage. Si le journal révèle plutôt un refus d’accès à un dépôt privé, concentrez-vous sur l’authentification et la disponibilité des éléments nécessaires : changer les options d’export ne résoudra pas ce problème.

Échec sur Mac distant : comparer l’environnement réel

Pourquoi l’export réussit-il en local mais échoue-t-il sur un Mac distant ?

Un résultat différent entre deux machines ne prouve pas que le Mac distant manque de puissance. Les causes à examiner en premier sont les différences de versions de Xcode ou de fastlane, le chemin des outils de ligne de commande, le répertoire de travail et l’accès aux éléments de signature. Une machine peut lancer un autre Xcode que celui que vous ouvrez dans l’interface, ou exécuter le lane sous un compte qui ne voit pas les mêmes fichiers et identifiants.

Commencez par consigner les versions et chemins effectivement utilisés lors de chaque exécution. Comparez ensuite le commit construit, les dépendances résolues, les variables de configuration nécessaires et le chemin transmis à gym. Vérifiez que les profils et certificats requis sont accessibles au processus qui exécute le lane, sans afficher leurs contenus sensibles dans les journaux.

Enfin, gardez le même Scheme, la même configuration et le même objectif de distribution pendant la comparaison. Si ces éléments changent en même temps que la machine, vous ne pourrez pas attribuer proprement l’échec à l’environnement. Une reprise ciblée, après avoir documenté une différence précise, est plus utile qu’une série de changements non liés.

Si le blocage vient bien de la récupération de la signature, revenez au diagnostic correspondant plutôt que d’attribuer l’erreur au caractère distant de la machine. Si les versions, les chemins, les fichiers accessibles et les paramètres du lane concordent, recherchez de nouveau la première erreur dans le journal : elle peut révéler un défaut de compilation ou une option d’export incompatible.

Contrôle de l’IPA : vérifier avant de conclure

Un code de sortie favorable ne suffit pas si le fichier attendu est absent, vide ou associé à une mauvaise cible. Vérifiez le répertoire d’export configuré dans le lane, le nom du fichier créé et son horodatage par rapport à l’exécution. Si plusieurs applications ou variantes sont construites, confirmez que l’IPA contrôlée correspond bien au Scheme et à la configuration que vous souhaitiez distribuer.

L’inspection doit aussi porter sur l’identité de l’application et la signature intégrée. Vérifiez que l’identifiant correspond à la cible attendue et que le mode de distribution concorde avec l’objectif annoncé, notamment pour une version App Store ou Ad Hoc. Pour une distribution Ad Hoc, contrôlez que le profil et les appareils autorisés correspondent au scénario de test. Le fait de pouvoir créer ou inspecter un IPA localement n’atteste pas que son importation sur une plateforme de distribution a réussi.

Arrêtez le diagnostic d’export lorsque l’Archive est achevée, que l’export se termine sans erreur, que le fichier attendu existe et que son identité ainsi que sa signature correspondent à l’objectif prévu. Si l’échec se produit ensuite pendant l’envoi ou le traitement, ouvrez un diagnostic distinct pour cette étape : évitez de relancer gym ou de modifier la signature sans indice qui relie ces actions au problème observé.

Liste de contrôle avant une nouvelle exécution

Cochez les éléments dans cet ordre ; si une réponse est négative, corrigez ce point avant de relancer le pipeline.

• [ ] J’ai conservé le journal complet et identifié la première erreur bloquante, au lieu de partir du seul message final.
• [ ] Je sais si l’échec se produit pendant la compilation, l’Archive, l’export ou après la création de l’IPA.
• [ ] Le projet ou l’espace de travail, le Scheme, la cible et la configuration de construction sont ceux de la version attendue.
• [ ] L’usage de l’IPA est défini et export_method correspond à cet usage.
• [ ] Les réglages export_options sont cohérents avec le projet, la cible et les outils installés.
• [ ] La signature automatique ou manuelle est configurée de façon cohérente avec les profils accessibles à l’exécution.
• [ ] Pour une comparaison local/distant, j’ai contrôlé les versions et chemins d’outils, le répertoire de travail et la visibilité des éléments nécessaires.
• [ ] Le fichier IPA existe à l’emplacement prévu et son identifiant ainsi que sa signature correspondent à la distribution visée.
• [ ] Je distingue l’export local de l’IPA de son envoi et de son traitement ultérieurs sur une plateforme de distribution.

Si vous construisez aujourd’hui sur votre propre Mac, vous connaissez déjà ses limites opérationnelles : l’espace utilisé par les outils et les archives, la dépendance à une machine disponible au moment du lancement et la gestion des profils dans un environnement parfois partagé avec d’autres tâches. Un Mac distant peut rendre l’environnement de construction accessible sans réserver votre poste à ces opérations, mais il ne corrigera ni un Scheme erroné ni un export_options incohérent. Si votre diagnostic confirme que le besoin porte sur un environnement Mac disponible pour reproduire la chaîne, vous pouvez comparer les solutions de Mac distant proposées par VPSMAC ; pour une exécution distribuée vers une équipe ou des utilisateurs situés dans l’ouest des États-Unis, consultez aussi les options VPSMAC en Silicon Valley. Vérifiez votre chaîne avec le même projet, les mêmes réglages et une procédure d’acceptation explicite : la location fournit un environnement, pas une garantie de correction du pipeline.