Pour les responsables des fusions et des releases

Confiez votre prochain merge à un nœud de build dédié

Générez d’abord un fichier ipa vérifiable à la main, puis confiez les tâches à la CI. Les étapes couvrent le démarrage, la connexion, l’intégration, la distribution et l’exploitation courante, sans vous imposer de réécrire votre pipeline existant.

Louer un Mac de build iOS Suivre les étapes

Comptez environ une heure pour une première intégration, sans garantie de délai : le téléchargement de dépendances volumineuses, l’installation de Xcode et la préparation des éléments de signature peuvent prendre du temps. Si le nœud est déjà disponible, commencez par vérifier la connexion.

Rassemblez les informations avant le démarrage

Choisissez un nœud adapté à votre projet

Si vous ne faites des builds qu’occasionnellement et disposez déjà d’un Mac inutilisé, l’héberger vous-même peut être plus économique. Si vous fusionnez du code plusieurs fois par jour et ne voulez pas gérer l’alimentation, le réseau et le refroidissement, envisagez un Mac dédié hébergé. OSXPort fournit un Mac mini physique complet, attribué à un seul client : ce n’est pas une machine virtuelle.

  1. 01

    Définissez les prérequis du projet

    Préparez une commande de build reproductible, un accès au code, la version de Xcode requise et les fichiers de verrouillage des dépendances. Commencez par une app, un scheme et une branche ; ne transformez pas cette première intégration en migration de toute votre chaîne de publication.

  2. 02

    Choisissez la configuration et la durée

    Sur la page de commande, choisissez le modèle, la région et une durée à la journée, à la semaine, au mois ou au trimestre. Port M4 Base convient aux essais légers ; pour les builds sur plusieurs branches et les tâches de simulateur, évaluez Port M4 Plus ; pour les grands projets à plusieurs targets, envisagez Port M4 Pro.

  3. 03

    Conservez les informations de mise à disposition

    Une fois la commande passée, consultez dans le portail l’adresse du nœud, le nom d’utilisateur de connexion et les identifiants. Le portail indique en temps réel si le nœud est disponible. Ajoutez son identifiant à l’inventaire de l’équipe et ne stockez pas le mot de passe dans le dépôt ni dans le corps d’un ticket.

  4. 04

    Choisissez la région la plus proche

    Régions disponibles : Singapour, Japon (Tokyo), Corée du Sud (Séoul), Hong Kong et côte ouest des États-Unis. Tenez compte de l’emplacement de votre équipe, mais aussi de celui du dépôt et des sources de dépendances ; vérifiez les performances réseau entre régions avec vos propres tâches de téléchargement et d’envoi.

Les trois configurations sont les suivantes : Apple Silicon M4 · 16 Go de mémoire unifiée · SSD 256 Go ; Apple Silicon M4 · 24 Go de mémoire unifiée · SSD 512 Go ; et Apple Silicon M4 Pro · 64 Go de mémoire unifiée · SSD 2 To. Pour une première intégration, évitez de lancer trop de builds en parallèle. Mesurez d’abord la mémoire utilisée, l’espace disque et la taille des artefacts pour un build.

Choisir une configuration et louer un nœud Consulter les identifiants dans le portail
Vérifiez d’abord la machine, puis intégrez-la au pipeline

Utilisez le même compte pour la connexion, la compilation et l’export

Lors de la première connexion, vérifiez l’adresse et le nom d’utilisateur du nœud, puis contrôlez les outils de développement. La session ci-dessous est un exemple, pas la sortie d’un nœud en temps réel ; les versions indiquées illustrent le format et peuvent différer de celles installées sur votre nœud.

Vérifiez ces trois niveaux avant de réinstaller quoi que ce soit

Connexion :Connectez-vous avec l’adresse, le port et le nom d’utilisateur fournis dans le portail. Lors de la première connexion, vérifiez l’empreinte de l’hôte. Si elle change de façon inattendue, vérifiez d’abord si le nœud a été remplacé ; ne contournez pas simplement la vérification. En cas de délai d’attente, contrôlez l’adresse et le réseau ; en cas d’échec d’authentification, vérifiez le nom d’utilisateur et les identifiants.

Outils :Utilisez xcode-select -p pour vérifier le répertoire développeur actif, puis xcodebuild -version pour noter la version. Si le projet exige une autre version, vérifiez d’abord qu’elle est installée, puis sélectionnez explicitement son chemin.

Projet :Installez les dépendances verrouillées dans le répertoire du projet et lancez d’abord manuellement la commande de build existante. Une connexion interactive réussie ne garantit pas que le runner en arrière-plan puisse accéder aux éléments de signature. Vérifiez ensuite avec le compte réellement utilisé par le runner.

Dans l’exemple, NODE_USER et NODE_ADDRESS doivent être remplacés par les valeurs fournies dans le portail ;App.ipa est le nom d’artefact utilisé à titre d’exemple. Si le projet gère fastlane avec Bundler, utilisez la commande prévue par le projet : bundle exec fastlane gym.

osxport · tokyo-node
$ ssh "$NODE_USER@$NODE_ADDRESS"
$ xcode-select -p
/Applications/Xcode.app/Contents/Developer
$ xcodebuild -version
Xcode 16.4
Build version 16F6
$ cd ~/workspace/App
$ fastlane gym
Creating archive
Exporting archive
Successfully exported and compressed dSYM file
Successfully exported and signed the ipa file
Exported ipa: ./build/App.ipa
$ ls -lh ./build/App.ipa

Critères de validation : la commande distante se termine correctement, la version correspond aux exigences du projet et le fichier existe au chemin indiqué. En cas d’échec de signature ou de compilation, conservez les journaux autour de la première erreur, pas seulement la dernière ligne.

Gardez la CI déjà utilisée par l’équipe

Réussissez une tâche manuelle avant d’enregistrer un runner

Les trois solutions s’exécutent sur le même nœud macOS physique. Les effectifs indiqués sont des repères d’organisation, pas une garantie de capacité. Déterminez le parallélisme en fonction de la mémoire utilisée par un build, du nombre de simulateurs exécutés simultanément et de l’espace disque nécessaire.

Runner auto-hébergé GitHub Actions

Idéal pour :Les équipes d’environ 3 à 15 personnes qui collaborent déjà via des fichiers de workflow. Inutile de mettre en place un ordonnanceur supplémentaire : enregistrez simplement le nœud au niveau d’un dépôt ou d’une organisation contrôlés.

  1. Dans les paramètres du dépôt ou de l’organisation, récupérez le paquet d’installation du runner et les instructions d’enregistrement correspondant à macOS et à l’architecture de la puce.
  2. Enregistrez le runner avec un compte d’exécution dédié, ajoutez un label défini par l’équipe et configurez runs-on pour utiliser ce label dans le workflow.
  3. Commencez par vérifier les versions et exécuter un build sans données sensibles, puis configurez le service en arrière-plan, l’injection des secrets et l’envoi des artefacts.

À éviter :Exposer un nœud contenant des éléments de signature aux pull requests externes non fiables. Un hôte dédié ne signifie pas que chaque workflow est isolé des autres.

Vérifier les critères du runner

GitLab Runner · shell executor

Idéal pour :Les équipes d’environ 3 à 30 personnes qui centralisent déjà le code et la gestion des accès dans GitLab. Le shell executor utilise directement Xcode et les outils en ligne de commande du nœud.

  1. Installez GitLab Runner pour macOS et enregistrez l’exécuteur à l’aide des informations fournies par le projet ou le groupe.
  2. Sélectionnez l’exécuteur shell , définissez un label dédié et limitez les branches protégées et les types de tâches autorisés à s’exécuter.
  3. Organisez la restauration des dépendances, la compilation, l’export et l’archivage des artefacts en étapes vérifiables séparément. Commencez avec un seul job à la fois.

À éviter :Exécuter sur le même shell executor les dépôts de clients qui ne se font pas confiance. Vous devez gérer vous-même le répertoire de travail et les permissions de l’hôte.

Vérifier les critères de l’exécuteur

Agent Jenkins

Idéal pour :Les équipes d’environ 10 à 30 personnes qui disposent déjà d’un contrôleur Jenkins et d’un processus d’approbation des releases. Ajoutez le nœud comme agent macOS sans migrer tout le pipeline.

  1. Créez un agent distinct dans le contrôleur, puis définissez son label, un répertoire de travail dédié et son compte d’exécution.
  2. Configurez la connexion selon les paramètres du contrôleur. Vérifiez la compatibilité de la version de Java requise avec l’environnement d’exécution de l’agent, puis activez son fonctionnement permanent.
  3. Faites sélectionner explicitement le label macOS aux tâches de test et vérifiez les variables d’environnement, les chemins des outils et les permissions d’archivage des artefacts.

À éviter :Créer un contrôleur uniquement pour un build occasionnel. Si vous disposez déjà d’une CI légère, ajouter un élément à gérer est généralement superflu.

Vérifier les critères de l’agent

Le runner est en ligne ? Vérifiez aussi ces quatre points

Effectuez les vérifications avec le compte réellement utilisé par le runner, pas uniquement depuis votre session interactive personnelle.
Élément à vérifierMéthode de vérificationCritère de réussite
Répertoire de travail et outilsExécutez whoami,pwd et xcodebuild -versionLe compte, le répertoire et la version de Xcode correspondent à la configuration de la tâche
Accès au dépôt et aux dépendancesRécupérez la branche indiquée avec les identifiants à permissions limitées injectés par la CI, puis restaurez les dépendances à partir des fichiers de verrouillageAucun jeton ni chemin non déclaré provenant d’un terminal personnel n’est nécessaire
Signature disponibleEffectuez l’archivage et l’export dans une tâche non interactiveAucune boîte de dialogue ne demande une validation manuelle ; les identifiants ne figurent pas dans les journaux
Reconnexion et stockage des artefactsVérifiez l’état du service en arrière-plan, puis récupérez les artefacts et les journaux à la fin de la tâcheLe runner peut rétablir la connexion ; les artefacts ne restent pas uniquement dans un répertoire de travail temporaire

Un même nœud peut héberger plusieurs points d’entrée de tâches contrôlés, mais ils partagent toujours le CPU, la mémoire unifiée et le SSD. Limitez d’abord le parallélisme à un seul build, puis augmentez-le progressivement à partir de vos mesures. Multiplier les noms de runners n’ajoute aucune ressource physique.

Codez sous Windows, compilez sous macOS

Exécutez les étapes iOS de Flutter sur le Mac distant

Windows convient au développement, aux commits et à la consultation des journaux ; la compilation et la signature iOS s’effectuent sur le Mac distant. Un nœud dédié ne dispense pas de disposer d’un abonnement valide au programme pour développeurs Apple, d’un certificat de signature, de sa clé privée et d’un profil de provisionnement correspondant à l’application.

  1. 01

    Verrouillez les dépendances

    Synchronisez le même commit et les mêmes fichiers de verrouillage, puis vérifiez la compatibilité entre Flutter, Dart, CocoaPods et Xcode. Commencez par exécuter flutter doctor -v pour contrôler la chaîne d’outils, puis flutter pub get; ne faites pas entrer dans le projet des chemins absolus provenant d’un autre ordinateur.

  2. 02

    Importez les éléments de signature

    Transférez le certificat, la clé privée et le profil de provisionnement par un moyen sécurisé approuvé par l’équipe. Importez le certificat dans un trousseau dédié accessible au compte utilisé pour le build. Configurez le profil de provisionnement et les options d’export, puis vérifiez que le bundle identifier, l’identifiant de l’équipe et le type de distribution correspondent.

  3. 03

    Lancez le build et récupérez l’artefact

    Exécutez flutter build ipa --release; si le projet nécessite des règles d’export spécifiques, indiquez le fichier correspondant avec --export-options-plist. L’artefact se trouve généralement dans build/ios/ipa/; vérifiez le chemin réellement indiqué, puis faites archiver l’artefact par la CI dans le stockage de l’équipe.

  4. 04

    Définissez le périmètre des tests

    Les tests sur simulateur et les builds automatisés peuvent être exécutés à distance. Les tests qui nécessitent un appareil physique local, ses capteurs ou la vérification de l’expérience d’utilisation doivent rester effectués sur l’appareil. Les équipes React Native peuvent également exécuter la compilation iOS sur le nœud, en restaurant les dépendances selon les scripts propres au projet.

Le cache accélère les builds, mais ne remplace pas une sauvegarde. Définissez les clés de cache d’après le projet, la version de Xcode et les fichiers de verrouillage des dépendances. En cas de problème de signature, vérifiez d’abord la validité, la clé privée et la correspondance avec le profil de provisionnement, plutôt que de supprimer tous les caches de build.

Vérifiez d’abord l’export, puis configurez l’envoi

Gérez séparément les identifiants de distribution et ceux de connexion au nœud

Pour distribuer via TestFlight, l’app doit être correctement configurée dans App Store Connect et disposer des permissions de publication nécessaires. L’API Key autorise l’envoi, mais ne remplace pas le certificat de signature et le profil de provisionnement requis pour la compilation.

Ordre de configuration

  1. Vérifiez que l’artefact peut être installé.Utilisez d’abord fastlane gym ou la commande déjà utilisée par le projet pour archiver et exporter l’app, puis vérifiez le bundle identifier, le numéro de version et le numéro de build.
  2. Créez une API Key.Une personne disposant des permissions requises crée une API Key App Store Connect avec le rôle approprié, note le Key ID et l’Issuer ID, puis conserve la clé privée en lieu sûr.
  3. Injectez-la dans la CI.Stockez la clé privée et les identifiants dans le gestionnaire de secrets de l’équipe. Au début de la tâche, générez un fichier de configuration à permissions limitées ; supprimez-le à la fin. Ne commitez ni la configuration ni la clé privée dans le dépôt.
  4. Envoyez le build et vérifiez son traitement.Exécutez pilot, puis vérifiez l’identifiant de l’app et le résultat de l’envoi. Un envoi réussi ne signifie pas que le build est déjà accessible aux testeurs : vérifiez aussi le traitement ultérieur et la distribution TestFlight.

Commande d’envoi si vous disposez déjà d’un ipa

fastlane pilot upload \
  --api_key_path "$ASC_API_KEY_JSON" \
  --ipa "$IPA_PATH" \
  --skip_waiting_for_build_processing true

ASC_API_KEY_JSON doit pointer vers un fichier temporaire de configuration d’API Key au format fastlane, etIPA_PATH vers le fichier ipa concerné. Avec Bundler, ajoutez bundle execdevant la commande.

Conservez la version de l’app, le numéro de build, l’identifiant du commit et le résultat de l’envoi. N’affichez ni la clé privée ni le fichier d’authentification complet dans les journaux.

En cas d’échec de l’envoi, diagnostiquez selon le type d’erreur

En cas d’erreur d’authentification, vérifiez le Key ID, l’Issuer ID, la clé privée et le rôle associé. Si le numéro de build existe déjà, modifiez-le sans reconfigurer le runner. En cas de problème de signature ou d’identifiant d’app, reprenez l’archivage et l’export. En validant séparément la compilation, la signature et l’envoi, vous éviterez de relancer toute la chaîne à chaque échec.

Intégrez les consignes de transfert au pipeline

Le nœud est disponible toute l’année ; vos tâches doivent aussi pouvoir migrer

Le nœud fonctionne 365 jours par an. Le centre de données prend en charge l’alimentation, le réseau et le refroidissement ; votre équipe gère les dépendances du projet, les secrets, la configuration des tâches et les sauvegardes. En cas d’anomalie matérielle, faites les vérifications nécessaires via un ticket et ne considérez pas un nœud unique comme l’unique copie à préserver.

Tenez à jour les consignes de reconstruction

Documentez les labels du runner, les versions des outils, les noms des variables d’environnement, l’installation des dépendances et les étapes d’importation des éléments de signature. Des scripts d’automatisation facilitent la reconstruction de l’environnement et son transfert à l’équipe.

Chiffrez les sauvegardes des certificats de signature et des clés privées. Récupérez les artefacts de build et les journaux dans le stockage de l’équipe. Vous pouvez décider de sauvegarder ou non DerivedData et les caches de dépendances selon leur coût, mais ils doivent pouvoir être régénérés.

Revoir la checklist de validation

En cas d’incident, conservez d’abord les éléments de diagnostic

Notez l’identifiant du nœud, la date et l’heure avec le fuseau horaire, la dernière tâche réussie et un résumé de l’erreur. Indiquez séparément si la connexion SSH fonctionne, si le runner est en ligne et si la tâche démarre, plutôt que de signaler simplement un « échec du build ».

Si vous pouvez encore vous connecter, exportez d’abord les données et journaux nécessaires, puis suspendez les nouvelles tâches. Ne joignez au ticket que des informations expurgées de toute donnée sensible. Si une autorisation est nécessaire pour le diagnostic, précisez-en la portée ; n’envoyez ni clé privée ni mot de passe complet.

Signaler un incident dans le portail

Après un remplacement du nœud, refaites les vérifications

Après vérification de l’incident par l’équipe d’assistance, confirmez la procédure à suivre via un ticket. Si le nœud doit être remplacé, mettez à jour l’adresse et les identifiants à partir des informations de mise à disposition, puis vérifiez de nouveau l’empreinte de l’hôte.

Restaurez les dépendances et les éléments de signature, réenregistrez ou rattachez le runner, puis lancez un build minimal. Une fois le nouveau nœud validé et prêt à recevoir des tâches, révoquez les anciens identifiants de connexion et les enregistrements de runners inutilisés.

Reprendre les vérifications de connexion

Avant de nettoyer le disque, définissez une politique de conservation : gardez les artefacts par version de publication, les journaux selon les exigences d’audit de l’équipe et faites tourner les caches puisqu’ils sont régénérables. Ne nettoyez pas le répertoire de travail pendant un build et ne changez pas globalement le chemin de Xcode en cours d’exécution.

Transférez ensemble la gestion des factures et du nœud

Vérifiez les échéances avant une release, sans compter sur le dernier rappel

Une location à la journée convient à un premier essai ou à des tâches de build ponctuelles ; à la semaine, à une période de travail intensive ; au mois ou au trimestre, à un usage régulier pour les builds nightly. Choisissez la durée en fonction du prix total affiché pour la période : le tarif journalier ne reflète pas le coût d’un usage prolongé.

Vérifiez les limites avant de modifier l’environnement

Les six questions fréquentes des équipes qui prennent le nœud en main

Puis-je installer Homebrew et les dépendances de mon projet ?

Vous pouvez gérer les outils de développement et les dépendances du projet comme sur un environnement macOS classique. Avant l’installation, vérifiez l’architecture, le chemin d’installation et les permissions requises, puis consignez les versions et les étapes d’installation. Pour la première intégration, reproduisez d’abord les dépendances existantes du projet. Évitez de mettre à jour tous les outils en même temps : il serait alors difficile de déterminer si un échec vient du projet ou d’un changement d’environnement.

Puis-je choisir la version de Xcode ?

Choisissez une version compatible avec le projet et vérifiez d’abord celles qui sont installées sur le nœud. Si vous devez en installer une autre, vérifiez l’espace disque, la méthode d’obtention et les exigences du projet ; ne supposez pas qu’une version donnée est préinstallée. Si plusieurs tâches partagent le nœud, définissez de préférence DEVELOPER_DIRdans l’environnement de la tâche, afin qu’un changement global n’affecte pas les autres tâches en cours.

Ai-je les droits root et le runner doit-il s’exécuter en tant que root ?

L’interface graphique macOS et la ligne de commande sont entièrement disponibles. Vérifiez les droits d’administration attribués et les permissions sudo associées aux identifiants fournis dans le portail. Si une étape d’installation nécessite des droits supplémentaires, vérifiez la procédure via un ticket. Ne considérez pas la connexion directe en root comme la méthode par défaut et évitez d’exécuter les tâches CI courantes avec des privilèges élevés. Gérez séparément les builds, les secrets et les répertoires de travail selon le principe du moindre privilège.

Plusieurs membres de l’équipe peuvent-ils utiliser le même nœud ?

Vous pouvez intégrer un même nœud dédié aux workflows de l’équipe, mais les ressources physiques de la machine n’augmentent pas avec le nombre d’utilisateurs. Attribuez des comptes séparés ou définissez clairement les points d’entrée des tâches, limitez le parallélisme et convenez d’un calendrier pour les changements d’environnement. L’équipe doit gérer elle-même les permissions de build et de signature de ses membres : ce nœud ne constitue pas un environnement multi-tenant isolé.

Le cache peut-il être supprimé par un autre client ?

Le Mac complet est attribué à un seul client et les ressources de build ne sont pas partagées avec d’autres clients. Le cache peut toutefois être affecté par les scripts de nettoyage de votre équipe, la gestion du disque ou les changements d’environnement. Considérez-le comme une couche d’accélération régénérable et sauvegardez séparément le code, les éléments de signature et les artefacts finaux. Après un remplacement du nœud, les dépendances doivent également pouvoir être restaurées à partir des fichiers de verrouillage.

Que faut-il joindre au ticket si l’intégration est bloquée ?

Indiquez l’identifiant du nœud, le type de CI, l’identifiant du commit concerné, la date et l’heure avec le fuseau horaire, ainsi que des journaux expurgés autour du premier échec. Précisez si la même commande se comporte différemment dans un terminal interactif et dans le runner. Supprimez les jetons d’accès, les clés privées, les mots de passe et les données métier figurant dans les chemins sensibles. Si l’équipe d’assistance a besoin d’approfondir le diagnostic, elle vous demandera de confirmer la portée de l’autorisation via le ticket.

Validez ce Mac de build avec une tâche réelle

Commencez par un essai à la journée avant de confier vos builds nightly à un usage régulier. Port M4 Base à partir de $19.7/jour ; conservez l’identifiant du commit, les journaux du build et les artefacts pour choisir une configuration adaptée à votre projet réel.

Louer un Mac de build iOS Ouvrir un ticket dans le portail