Builds iOS

Compilez et publiez vos apps iOS sur TestFlight et l'App Store grâce à l'infrastructure Mac dédiée de Capgo.

Ce que vous allez apprendre

• Vous apprendrez à envoyer votre app via Capgo Native Build
• Vous apprendrez à configurer les certificats pour Capgo Native Build

Prerequisites

• Un compte Capgo (un essai gratuit suffit pour commencer)
• Votre app déjà enregistrée dans Capgo (exécutez bunx @capgo/cli@latest app add si non)
• Aucun Mac requis : Capgo Build compile et signe votre app iOS dans le cloud, vous pouvez donc le faire depuis macOS, Windows ou Linux
• Un compte Apple Developer valide (99 $/an) (vous devez disposer des droits d'administrateur ou de propriétaire sur le compte Apple Developer)
• Votre app doit compiler sans erreur (dans Xcode en local, ou avec Capgo Build)
• Une app Capacitor
• Une icône configurée pour l'app. Les apps sans icône ne peuvent pas être envoyées sur l'App Store.

Remarque

J'utiliserai l'application suivante pour ce tutoriel : https://github.com/Cap-go/capgo-tutoriel-native-build-app

Avant de commencer sur les portails Apple

Avant de configurer vos certificats ou de lancer votre premier upload TestFlight, assurez-vous que votre compte et votre équipe Apple sont prêts :

• Activez l'authentification à deux facteurs pour le compte Apple utilisé lors de l'inscription
• Choisissez le bon type d'adhésion :
  • Individuel / Entrepreneur individuel: votre nom légal devient le nom du vendeur sur l'App Store
  • Organisation: nécessite une entité juridique, un numéro D-U-N-S, un site web public de l'entreprise, une adresse e-mail professionnelle sur le domaine de l'entreprise et une personne habilitée à engager l'organisation dans les accords d'Apple
• Utilisez un compte ayant accès à la fois à Apple Developer et App Store Connect pour les certificats, les fiches d'application, les clés API et TestFlight
• Fixez votre bundle ID final dès le début. Le modifier plus tard implique généralement de refaire toute la configuration sur l'App Store
• Préparez ces éléments App Store Connect avant l'App Review : URL de support, URL de politique de confidentialité, classification d'âge, captures d'écran, conformité à l'exportation et coordonnées pour l'App Review

Remarque

Références officielles utiles :

• Devenir membre du Apple Developer Program
• Soumettre vos apps et jeux
• Informations sur les versions de plateforme dans App Store Connect

Attention

Apple met régulièrement à jour son exigence minimale de SDK. À partir de 28 avril 2026, les apps iPhone et iPad envoyées sur App Store Connect doivent être compilées avec iOS & iPadOS 26 SDK ou version ultérieure.

Recommandé : onboarding automatisé

Vous n'avez rien à faire manuellement. L'onboarding de Capgo crée et configure vos identifiants de signature iOS (certificat de distribution + profil de provisionnement) pour vous — voici la méthode recommandée :

bunx @capgo/cli@latest build init --platform ios

Le guide manuel ci-dessous ne s'adresse qu'à ceux qui préfèrent configurer eux-mêmes leurs identifiants ou qui veulent comprendre exactement ce que Capgo fait sous le capot.

Le premier build manuel

Avant de commencer à compiler l'application avec Capgo, nous devons d'abord la configurer et effectuer un premier build TestFlight manuellement. Effectuer un build manuel au préalable présente plusieurs avantages :

• Vous configurerez le certificat de distribution sur votre machine locale
• Vous créerez la fiche App Store si ce n'est pas déjà fait
• Vous pourrez identifier d'éventuels problèmes de build liés à votre application code

Avant de commencer, vous devez avoir installé le certificat de distribution sur votre machine locale. C'est une étape assez complexe, mais je vous l'explique ci-dessous.

Configuration du certificat de distribution

1. Ouvrez Xcode

2. Cliquez sur Xcode -> Settings... Sinon, vous pouvez utiliser le raccourci Cmd + ,

   

3. Accéder à Accounts

4. Trouvez le compte Apple associé au compte Apple Developer

5. Trouvez l'équipe que vous utiliserez pour déployer l'app

6. Cliquez sur Manage Certificates... bouton

7. Assurez-vous de voir le certificat de distribution dans la liste

8. Si ce n'est pas le cas, vous devez créer un nouveau certificat

   Remarque

   Apple limite le nombre de certificats de distribution à 3. Si vous en avez plus de 3, vous devrez en supprimer un pour en créer un nouveau. Je ne traiterai pas ce point dans ce tutoriel.

   1. Cliquez sur + bouton puis sur Apple Distribution
   2. Le certificat sera créé automatiquement. Vous pourrez le voir dans la liste. Reportez-vous à l'étape précédente pour confirmer sa présence.

Maintenant que le certificat de distribution est installé, vous pouvez lancer le processus de build.

Build manuel vers TestFlight

1. Ouvrez l'app dans Xcode

   Exécutez bunx cap open ios pour ouvrir l'app dans Xcode.

2. Cherchez et cliquez sur le archive bouton

   Dans la barre d'outils Xcode, cherchez et cliquez sur le product -> archive .

   

3. Attendez la fin du build

4. Cliquez sur Distribute App bouton

   

5. Sélectionnez TestFlight Internal Only comme méthode de distribution et cliquez sur Distribute bouton

   

6. Configurer la fiche de l'application

   Remplissez les champs suivants :

   1. Nom : le nom de votre application - visible sur l'App Store
   2. SKU - le SKU de votre application - utilisé pour identifier votre application sur l'App Store
   3. Langue principale - la langue principale de votre application

   Ensuite, cliquez sur le next bouton

   

7. Si la création de l'enregistrement de l'app échoue, essayez de fermer la fenêtre et de relancer l'archive de l'app.

8. Attendez la fin de l'upload

9. Si tout s'est bien passé, vous devriez voir l'écran suivant

10. Cliquez sur Done bouton

Vous pourriez penser que tout est prêt et que votre app est déjà visible dans TestFlight, mais il reste encore quelques étapes :

1. Ajoutez-vous à TestFlight
2. Complétez la conformité d'exportation pour que le build soit testable
3. Remplissez les métadonnées App Store Connect requises (URL de support, URL de politique de confidentialité, classification d'âge)
4. Préparez des captures d'écran correspondant aux appareils que vous supportez réellement
5. Ajoutez les coordonnées de contact pour l'App Review et les identifiants de test avant la soumission en production

Commençons par le premier point :

S'ajouter à TestFlight

1. Allez sur la page App Store Connect page

2. Connectez-vous avec votre compte Apple Developer

3. Sélectionnez l'équipe utilisée lors de la création de la fiche de l'app. Si vous n'avez qu'un seul compte developer, vous pouvez ignorer cette étape.

4. Cliquez sur Apps bouton

5. Trouvez l'app créée à l'étape précédente et cliquez dessus

6. Cliquez sur TestFlight bouton

7. Cliquez sur Internal Testers plus bouton

8. Créer un nouveau groupe

   Je nomme le groupe « internal ». Vous pouvez le nommer comme vous le souhaitez.

   

9. Cliquez sur Invite testers bouton

10. Ajoutez-vous au groupe

    Cherchez votre nom dans la liste et cochez la case à côté de votre nom. (Il se peut que vous deviez rafraîchir la page pour vous voir) Ensuite, cliquez sur la Add .

    

11. Vérifiez que vous avez été ajouté au groupe

    Vous devriez maintenant apparaître dans le groupe.

    

Félicitations 🎉 Vous vous êtes ajouté à TestFlight. Il ne reste plus qu'une étape avant de pouvoir configurer Capgo Native Build.

Configuration des informations de conformité

Vous devez maintenant garantir à Apple que votre application n'utilise pas de chiffrement non standard (comme un algorithme personnalisé). Si votre application utilise un chiffrement non standard, je vous suggère de lire la documentation Apple sur la gestion de ce point. Il existe deux méthodes pour le faire :

1. Vous pouvez le faire manuellement à chaque fois que vous compilez votre app.
2. Vous pouvez configurer votre fichier plist pour définir automatiquement cette valeur sur false.

Commençons par la première méthode :

1. Suivez toutes les étapes de la section précédente pour trouver la section TestFlight dans App Store Connect

2. Cliquez sur Builds -> iOS

3. Trouvez le build dont les informations de conformité sont manquantes et cliquez sur Manage

4. Sélectionnez l'option qui décrit le mieux votre app

   Pour moi, il s'agit de none, mais cela peut varier pour vous. Ensuite, cliquez sur enregistrer

   

5. Votre app devrait maintenant afficher ready to test

   

Pour la deuxième option, voici les étapes :

1. Ouvrez le Info.plist fichier

2. Ajoutez la clé suivante :

   <key>ITSAppUsesNonExemptEncryption</key>
   <false/>

3. Enregistrer le fichier

Remarque

Voici la documentation officielle d'Apple sur la manière de les informer de votre conformité aux réglementations d'exportation de chiffrement.

Installer l'application TestFlight et accepter l'invitation

Maintenant, vous êtes PRÊT À TESTER votre application dans TestFlight. Au préalable, vous devez effectuer les étapes suivantes :

1. Téléchargez le Application TestFlight depuis l'App Store sur votre appareil iOS/iPadOS
2. Acceptez l'invitation pour tester votre application

Je vais passer les détails sur l'installation de l'application TestFlight sur votre appareil. Si vous ne savez pas comment installer une application, Google propose d'excellents guides pour vous aider.

Pour accepter l'invitation, vous recevrez un e-mail d'Apple contenant un lien pour l'accepter.

1. Ouvrez l'e-mail d'Apple contenant le lien pour accepter l'invitation

2. Cliquez sur View in TestFlight bouton

3. Cliquez sur Install bouton

4. Installer l'application sur votre appareil

   Si vous avez déjà installé l'app via Xcode, l'écran suivant peut s'afficher. Veuillez cliquer sur le install .

5. Attendez que l'app s'installe

6. Cliquez sur Open bouton et cliquez dessus

Félicitations 🎉 Vous avez accepté l'invitation pour tester votre app sur TestFlight. Vous pouvez maintenant configurer Capgo Native Build pour compiler et soumettre votre app à TestFlight.

Configuration de Capgo Native Build

Quelques éléments sont à configurer dans Capgo Native Build pour pouvoir compiler et soumettre votre app à TestFlight. Voici la liste des éléments à transmettre à Capgo CLI :

Paramètre	Description
--platform	La plateforme cible (ios)
--apple-team-id	Votre Apple Developer Team ID (à trouver dans Portail Apple Developer)
--apple-key	Chemin vers votre fichier de clé API App Store Connect (.p8 fichier)
--apple-key-id	L'ID de votre clé API App Store Connect
--apple-issuer-id	Votre Issuer ID App Store Connect
--certificate	Chemin vers votre certificat de distribution (.p12 fichier)
--ios-provisioning-profile	Mapping du profil de provisionnement (bundleId=path ou simplement le chemin pour un profil unique)

Exemple de commande :

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile '/path/to/profile.mobileprovision'

ID d'équipe

Commençons par le Team ID. Le trouver est assez simple.

1. Accéder à Compte Apple Developer et faire défiler vers le bas

2. Trouvez le Team ID

   

clé Apple, Apple key ID et Apple issuer ID

Passons maintenant à la clé Apple.

macOS : laissez Capgo créer cette clé pour vous

Sur macOS, capgo build init peut créer cette clé API App Store Connect pour vous. Choisissez « Non — en créer une pour moi » et une fenêtre guidée ouvre App Store Connect, vous accompagne à chaque étape et récupère automatiquement la clé, le Key ID et l'Issuer ID — sans copier-coller. Les étapes manuelles ci-dessous sont l'alternative (et la méthode sur Windows ou Linux).

1. Accéder à Page utilisateur et accès App Store Connect

   Remarque

   Le lien ne fonctionne parfois pas. Rechargez la page s'il ne marche pas chez vous.

2. Sélectionnez la bonne équipe dans le menu déroulant

   1. Cliquez sur votre nom en haut à droite
   2. Cliquez sur l'équipe que vous souhaitez utiliser

3. Cliquez sur Integrations bouton

4. Trouvez le issuer

   Attention

   Ceci DOIT ÊTRE SAUVEGARDÉ - vous en aurez besoin plus tard

   Cliquez sur copy bouton pour copier l'émetteur

5. Cliquez sur le bouton plus

6. Définissez le nom de la clé et réglez l'accès sur App manager et cliquez sur Generate bouton

7. Enregistrez l'ID de la clé

   Attention

   Ceci DOIT ÊTRE SAUVEGARDÉ - vous en aurez besoin plus tard

   

8. Télécharger la clé

   Attention

   Ceci DOIT ÊTRE SAUVEGARDÉ - vous en aurez besoin plus tard

   Danger

   NE PARTAGEZ JAMAIS CETTE CLÉ - UTILISEZ-LA UNIQUEMENT DANS LE CAPGO CLI

   

   

Félicitations 🎉 Vous avez créé la clé Apple, l'ID de clé Apple et l'ID d'émetteur Apple.

Certificat

Vous êtes maintenant prêt à exporter le certificat. Pour rappel, l'une des premières étapes de ce guide consistait à configurer le certificat de distribution.

Cependant, Apple a décidé, dans son infinie sagesse, que la méthode pour exporter un certificat est assez différente de celle pour le créer 🙃 Passons à la configuration :

1. Ouvrez l'accès au trousseau (Keychain Access)

   1. Cliquez Command + Space pour ouvrir la barre de recherche
   2. Recherchez Keychain Access
   3. Cliquez sur Keychain Access app

2. Sélectionnez l’ login catégorie et cliquez sur la My Certificates bouton

3. Trouvez votre certificat dans la liste

   Le certificat doit porter le nom Apple Distribution: [Your Name/Company] (your team ID)

4. Faites un clic droit sur le certificat et sélectionnez Export

5. Enregistrer le certificat en tant que .p12 fichier

   Attention

   Ceci DOIT ÊTRE SAUVEGARDÉ - vous en aurez besoin plus tard

   1. Veillez à choisir un nom explicite pour le fichier du certificat
   2. Assurez-vous que le format du fichier est défini sur Personal Information Exchange (.p12)
   3. Cliquez sur Save bouton

   

6. Lorsqu'on vous demande le mot de passe, vous pouvez soit :

   • Ignorer le mot de passe (recommandé pour plus de simplicité) : Cliquez OK sans saisir de mot de passe
   • Définir un mot de passe : Si vous préférez protéger votre certificat par un mot de passe, vous pouvez le définir ici. Les fichiers .p12 les fichiers sont entièrement pris en charge par le Capgo CLI — fournissez simplement le mot de passe via le --p12-password option lors de l'exécution de la commande de configuration.

   

7. Lorsque le « mot de passe du trousseau d'accès » est demandé, saisissez le mot de passe que vous utilisez pour ouvrir votre session Mac

   Saisissez le mot de passe de votre session Mac. Ensuite, cliquez sur le Allow .

   

Félicitations 🎉 Le certificat a été exporté.

Profil de provisionnement

Vous êtes maintenant prêt à exporter le profil de provisionnement. Je vous le promets, c'est la dernière chose que vous aurez à récupérer chez Apple.

1. Accéder à Profils Apple Developer

2. Sélectionnez la bonne équipe dans le menu déroulant

   1. Cliquez sur votre nom en haut à droite
   2. Cliquez sur l'équipe que vous souhaitez utiliser

3. Assurez-vous d'être sur la bonne page Elle devrait ressembler à ceci ; si ce n'est pas le cas, cliquez sur profiles dans la barre latérale

   

4. Cliquez sur + bouton

5. Sélectionnez le type de profil Sélectionner App Store Connect et cliquez sur Continue bouton

   

6. Sélectionnez l'app que vous souhaitez compiler

   Trouvez votre app dans le menu déroulant et cliquez sur Continue bouton

   

7. Sélectionnez le certificat de distribution approprié

   Sélectionnez le certificat que vous avez exporté à l'étape précédente et cliquez sur Continue bouton

   

   Si vous ne savez pas quel certificat choisir, retournez dans l'Accès au trousseau pour retrouver celui que vous avez exporté. Vérifiez ensuite sa date d'expiration.

   

8. Nommez le profil

   Donnez un nom au profil et cliquez sur Generate bouton

   Astuce

   Le nom du profil est automatiquement extrait par le Capgo CLI — pas besoin de vous en souvenir.

   

9. Télécharger le profil

   Cliquez sur Download bouton pour télécharger le profil

   Attention

   Ce fichier DOIT ÊTRE SAUVEGARDÉ - vous en aurez besoin plus tard

   

Félicitations 🎉 Vous avez maintenant tout ce qu'il faut pour configurer Capgo Native Build.

Attention

Ne commitez jamais les identifiants que vous venez de créer dans votre dépôt. Gardez-les en sécurité ! 🔒

Exécution de la commande de configuration

C'est fait ! Vous avez maintenant tout ce qu'il faut pour configurer Capgo Native Build.

La commande que vous devrez exécuter est :

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --ios-provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision

Remplacer les valeurs d'espace réservé

Remplacez les valeurs ci-dessus par vos véritables identifiants récupérés lors des étapes précédentes :

• --apple-team-id: Votre Apple Team ID
• --apple-key: Chemin vers votre fichier .p8 fichier de clé
• --apple-key-id: Votre Apple Key ID
• --apple-issuer-id: Votre Apple Issuer ID
• --certificate: Chemin vers votre fichier .p12 certificat
• --ios-provisioning-profile: Chemin vers votre fichier .mobileprovision exporté (bundle ID déduit automatiquement pour les profils uniques)

Si tout s'est bien passé, vous verrez la sortie suivante :

Échec de l'auth Apple ? Synchronisez votre horloge

Si la clé API d’App Store Connect semble correcte mais que l’authentification échoue toujours, synchronisez l’horloge de votre ordinateur et réessayez. Capgo signe le JWT d’Apple avec l’heure locale de votre système, et Apple rejette les tokens dont l’expiration est fixée à plus de 20 minutes dans le futur. Un décalage de quelques secondes seulement peut suffire à faire échouer cette étape.

Consultez le guide de dépannage du builder pour les étapes de synchronisation de l’horloge.

Configuration CI/CD (GitHub Actions)

Si vous avez déjà terminé ID d'équipe, clé Apple, Apple key ID et Apple issuer ID, Certificat, et Profil de provisionnement, vous avez déjà tout ce qu'il faut pour la CI/CD.\nCette section explique uniquement comment passer ces valeurs en tant que secrets GitHub Actions et variables d'environnement.

1) Convertir les fichiers d'identifiants en base64 sur une seule ligne

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

Astuce

Les secrets GitHub doivent être des valeurs sur une seule ligne. tr -d '\n' supprime les sauts de ligne de la sortie base64.

2) Créer les secrets du dépôt

Dans GitHub > Repository > Settings > Secrets and variables > Actions, ajoutez :

Nom du secret	Valeur
CAPGO_TOKEN	Votre token Capgo API
APP_STORE_CONNECT_TEAM_ID	Team ID de ID d'équipe
APPLE_KEY_ID	Key ID de clé Apple, Apple key ID et Apple issuer ID
APPLE_ISSUER_ID	Issuer ID de clé Apple, Apple key ID et Apple issuer ID
BUILD_CERTIFICATE_BASE64	Contenu de certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Généré par CLI — copiez depuis .capgo-credentials fichier
APPLE_KEY_CONTENT	Contenu de apple_key_base64.txt
P12_PASSWORD (facultatif)	Votre .p12 mot de passe s'il a été défini lors de l'export

3) Utilisez des variables d'env dans votre workflow GitHub Actions

.github/workflows/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

Astuce

Avec cette configuration, la CI envoie les identifiants uniquement via des variables d'environnement. Vous n'avez pas besoin de commiter les fichiers de signature ou de les envoyer comme artefacts de workflow.

Lancement du build

Vous êtes maintenant prêt à lancer votre premier build.

Exécutez la commande suivante pour compiler votre application :

bunx @capgo/cli@latest build request --platform ios

Félicitations 🎉 À ce stade, vous avez compilé votre application avec succès et elle est prête à être soumise à l'App Store.

Soumettre pour examen sur l'App Store

Le flux de build classique de l'App Store envoie le build vers App Store Connect/TestFlight. Si votre release CI doit également joindre le build TestFlight traité à la version de l'App Store et la soumettre pour examen, passez --submit-to-store-review avec un build de release :

npx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --build-mode release \
  --ios-distribution app_store \
  --submit-to-store-review \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales" \
  --no-ios-automatic-release

Cela nécessite les identifiants de clé API d'App Store Connect (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, et APP_STORE_CONNECT_TEAM_ID). L'envoi de mots de passe spécifiques à l'app et ad_hoc la distribution ne peut pas soumettre de build pour examen. --store-release-name est la version de l'App Store ; si omis, Capgo lit MARKETING_VERSION depuis le projet Xcode. --store-release-notes est le texte de secours « Nouveautés » de l'App Store, et chaque --store-release-notes-locale "locale=notes" entrée peut le remplacer pour une localisation du store. Utilisez --ios-automatic-release pour une release automatique après approbation d'Apple, ou --no-ios-automatic-release pour attendre une release manuelle. --ios-testflight-groups est toujours disponible pour la distribution bêta externe, mais n'est pas requis pour la soumission à l'App Store.

Mode de distribution Ad-Hoc

Par défaut, Capgo compile les apps iOS pour une distribution sur l'App Store (TestFlight + App Store). Si vous avez besoin de builds ad-hoc à la place (pour des tests internes ou la collecte d'artefacts CI), vous pouvez utiliser le --ios-distribution flag.

Remarque

La distribution ad-hoc est pas identique à la distribution Enterprise (In-House). La distribution Enterprise nécessite un compte Apple Developer Enterprise distinct et utilise des profils de provisionnement différents. Capgo prend actuellement en charge app_store et ad_hoc modes.

Quand utiliser le mode ad-hoc

• Vous souhaitez distribuer des IPA directement aux appareils enregistrés (sans TestFlight)
• Vous n'avez pas de clé API App Store Connect ou vous ne souhaitez pas en utiliser
• Vous voulez récupérer les artefacts de build via --output-upload sans soumettre à l'App Store

Prérequis

Les builds ad-hoc ont moins de prérequis que les builds App Store :

Identifiant	Obligatoire ?
Certificat de distribution (.p12)	Oui
Profil de provisionnement Ad-hoc (.mobileprovision)	Oui
ID d'équipe (--apple-team-id)	Oui
Clé API App Store Connect (.p8)	Non
ID de clé Apple / ID de l'émetteur Apple	Non

Remarque

Dans ad_hoc mode, --apple-key, --apple-key-id, et --apple-issuer-id ne sont pas pris en charge et sont ignorés. C'est pourquoi les deux lignes App Store Connect ci-dessus n'affichent pas les flags CLI ad-hoc ; ces options s'appliquent uniquement au app_store mode.

Attention

Sans clé API App Store Connect, l'incrémentation automatique du numéro de build utilise un repli basé sur l'horodatage. Pour supprimer l'avertissement, passez --skip-build-number-bump.

Créer un profil de provisionnement ad-hoc

Suivez les mêmes étapes que Profil de provisionnement, mais à l'étape 5, sélectionnez Ad Hoc au lieu de App Store:

1. Accéder à Profils Apple Developer
2. Cliquez sur les + bouton
3. Sélectionnez Ad Hoc et cliquez sur Continuer
4. Sélectionnez votre app et votre certificat de distribution
5. Sélectionnez les appareils à enregistrer
6. Nommer et télécharger le profil

Enregistrement des identifiants ad-hoc

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --ios-provisioning-profile './adhoc_profile.mobileprovision'

Non --apple-key, --apple-key-id, ou --apple-issuer-id nécessaire.

Exécuter un build ad-hoc

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

Pour récupérer l'IPA en tant qu'artefact de build, ajoutez --output-upload:

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

CI/CD avec des builds ad-hoc

Pour les GitHub Actions, vous avez besoin de moins de secrets que pour les builds App Store :

.github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_ADHOC }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

Astuce

Notez que APPLE_KEY_ID, APPLE_ISSUER_ID, et APPLE_KEY_CONTENT ne sont pas nécessaires pour les builds ad-hoc.

Apps avec extensions (signature multi-target)

Si votre app inclut des extensions (share extensions, widgets, notification service extensions, etc.), chaque cible d'extension nécessite son propre profil de provisionnement. Capgo prend cela en charge via le flag --ios-provisioning-profile répétable.

Exemple : App + Share Extension

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile "com.example.app=./app_profile.mobileprovision" \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Chaque --ios-provisioning-profile flag associe un bundle ID à son fichier de profil de provisionnement. Le CLI :

1. Lit chaque fichier mobileprovision
2. Extrait automatiquement le nom du profil depuis le plist intégré
3. Encode le fichier en Base64
4. Stocke le tout sous forme d'un seul CAPGO_IOS_PROVISIONING_MAP credential

Astuce

Vous avez besoin d'un seul certificat de distribution pour toutes les cibles — seuls les profils de provisionnement diffèrent par cible.

Migration depuis un profil unique

Si vous utilisiez auparavant BUILD_PROVISION_PROFILE_BASE64 (un profil unique), lancez :

bunx @capgo/cli@latest build credentials migrate --platform ios

Cela convertit vos identifiants existants à profil unique vers le nouveau CAPGO_IOS_PROVISIONING_MAP format et supprime les clés obsolètes (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Après la migration, ajoutez des profils d'extension avec la update commande (fusion additive) :

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Astuce

Utiliser update (pas save) pour ajouter des profils aux identifiants existants. La update commande fusionne les nouveaux profils avec les profils existants. Utilisez save uniquement pour configurer tous les identifiants depuis zéro.

Troubleshooting

Le profil de provisionnement n’inclut pas la capacité XYZ.

Il arrive que vous rencontriez l'erreur suivante :

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

Cela se produit parce que vous avez activé une nouvelle capacité après la création du profil de provisionnement. L'ancien profil de provisionnement ne prend pas encore en compte cette nouvelle capacité.

Pour corriger cela, vous devez régénérer le profil de provisionnement.

1. Ouvrez Portail Apple Developer
2. Sélectionnez la bonne équipe dans le menu déroulant
3. Cliquez sur Profiles bouton
4. Trouvez le profil de provisionnement à régénérer
5. Cliquez sur Edit bouton
6. Cliquez sur Save bouton
7. Cliquez sur Download bouton
8. Relancez la commande de configuration Capgo Native Build avec le nouveau profil téléchargé.

Cela devrait résoudre le problème.

Autres problèmes

Si, pour une raison quelconque, vous rencontrez des problèmes avec Capgo Native Build, la configuration des identifiants ou la compilation de l'app, n'hésitez pas à nous contacter via notre support.

Continuer avec les builds iOS

Si vous utilisez Builds iOS pour planifier l'automatisation CI/CD, et le connecter avec CI/CD Capgo pour le workflow produit dans le CI/CD de Capgo, Capgo Native Build pour le workflow produit dans les Native Builds de Capgo, Intégrations Capgo pour le workflow produit dans les intégrations de Capgo, Intégration CI/CD pour le détail d'implémentation dans l'intégration CI/CD, et Intégration GitHub Actions pour les détails d'implémentation de l'intégration GitHub Actions.