Dépannage

Solutions aux problèmes courants lors de la compilation d’applications natives avec Capgo Cloud Build.

Échecs de build

”Échec du téléversement” ou “Timeout de connexion”

Symptômes :

• Le build échoue pendant le téléversement du projet
• Erreurs de timeout après 60 secondes

Solutions :

1. Vérifiez votre connexion internet

   # Testez la connexion à Capgo
   curl -I https://api.capgo.app

2. Réduisez la taille du projet

   • Assurez-vous que node_modules/ n’est pas téléversé (devrait être auto-exclu)
   • Vérifiez les fichiers volumineux dans votre projet :

   find . -type f -size +10M

3. Vérifiez l’expiration de l’URL de téléversement

   • Les URL de téléversement expirent après 1 heure
   • Si vous obtenez une erreur d’URL expirée, relancez la commande de build

Astuce

Les grands projets (>200MB) peuvent atteindre les limites de timeout. Contactez le support pour les options entreprise.

”Timeout du build après 10 minutes”

Symptômes :

• Le build dépasse le temps maximum autorisé
• Le statut affiche timeout

Solutions :

1. Optimisez les dépendances

   • Supprimez les packages npm non utilisés
   • Utilisez npm prune --production avant de compiler

2. Vérifiez les problèmes réseau dans le build

   • Certaines dépendances peuvent télécharger de gros fichiers pendant le build
   • Envisagez la mise en cache préalable avec un fichier de verrouillage

3. Examinez les dépendances natives

   # iOS - vérifiez le Podfile pour les dépendances lourdes
   cat ios/App/Podfile
   
   # Android - vérifiez build.gradle
   cat android/app/build.gradle

4. Contactez le support

   • Si votre application nécessite légitimement plus de temps
   • Nous pouvons ajuster les limites pour des cas d’utilisation spécifiques

Problèmes d’authentification

”Clé API invalide” ou “Non autorisé”

Symptômes :

• Le build échoue immédiatement avec une erreur d’authentification
• Erreurs 401 ou 403

Solutions :

1. Vérifiez que la clé API est correcte

   # Testez avec une commande simple
   npx @capgo/cli@latest app list

2. Vérifiez les permissions de la clé API

   • La clé doit avoir les permissions write ou all
   • Vérifiez dans le tableau de bord Capgo sous Clés API

3. Assurez-vous que la clé API est lue

   # Vérifiez la variable d'environnement
   echo $CAPGO_TOKEN
   
   # Ou vérifiez le fichier .capgo local
   cat .capgo

4. Réauthentifiez-vous

   npx @capgo/cli@latest login

”Application introuvable” ou “Pas de permission pour cette application”

Symptômes :

• L’authentification fonctionne mais erreur spécifique à l’application

Solutions :

1. Vérifiez que l’application est enregistrée

   npx @capgo/cli@latest app list

2. Vérifiez que l’ID de l’application correspond

   • Vérifiez l’appId dans capacitor.config.json
   • Assurez-vous que la commande utilise le bon ID d’application

3. Vérifiez l’accès à l’organisation

   • Vérifiez que vous êtes dans la bonne organisation
   • La clé API doit avoir accès à l’organisation de l’application

Problèmes de build iOS

”Échec de la signature du code”

Symptômes :

• Le build échoue pendant la phase de signature du code
• Erreurs Xcode concernant les certificats ou profils

Solutions :

1. Vérifiez que le type de certificat correspond au type de build

   • Les builds de développement nécessitent des certificats Development
   • Les builds App Store nécessitent des certificats Distribution

2. Vérifiez que le certificat et le profil correspondent

   # Décodez et inspectez votre certificat
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. Assurez-vous que le profil de provisionnement est valide

   • Vérifiez la date d’expiration
   • Vérifiez qu’il inclut votre App ID
   • Confirmez qu’il inclut le certificat

4. Régénérez les identifiants

   • Supprimez l’ancien certificat/profil
   • Créez-en de nouveaux dans le portail Apple Developer
   • Réencodez et mettez à jour les variables d’environnement

”Le profil de provisionnement n’inclut pas le certificat de signature”

Symptômes :

• Xcode ne trouve pas le certificat dans le profil

Solutions :

1. Téléchargez le dernier profil d’Apple

   • Allez sur Apple Developer → Certificats, ID et profils
   • Téléchargez le profil de provisionnement
   • Assurez-vous qu’il inclut votre certificat

2. Vérifiez que le certificat est dans le profil

   # Extrayez le profil
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # Affichez le contenu du profil
   security cms -D -i profile.mobileprovision

3. Recréez le profil avec le bon certificat

   • Dans le portail Apple Developer, modifiez le profil
   • Assurez-vous que votre certificat de distribution est sélectionné
   • Téléchargez et réencodez

”Échec de l’authentification App Store Connect”

Symptômes :

• Le téléversement vers TestFlight échoue
• Erreurs de clé API

Solutions :

1. Vérifiez les identifiants de la clé API

   • Vérifiez APPLE_KEY_ID (devrait faire 10 caractères)
   • Vérifiez APPLE_ISSUER_ID (devrait être au format UUID)
   • Vérifiez que APPLE_KEY_CONTENT est correctement encodé en base64

2. Testez la clé API localement

   # Décodez la clé
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Testez avec fastlane (si installé)
   fastlane pilot list

3. Vérifiez les permissions de la clé API

   • La clé nécessite le rôle “Developer” ou supérieur
   • Vérifiez dans App Store Connect → Utilisateurs et accès → Clés

4. Assurez-vous que la clé n’est pas révoquée

   • Vérifiez dans App Store Connect
   • Générez une nouvelle clé si nécessaire

”Échec de l’installation de Pod”

Symptômes :

• Le build échoue pendant l’installation de CocoaPods
• Erreurs de Podfile

Solutions :

1. Vérifiez que Podfile.lock est committé

   git status ios/App/Podfile.lock

2. Testez l’installation de pod localement

   cd ios/App
   pod install

3. Vérifiez les pods incompatibles

   • Examinez le Podfile pour les conflits de version
   • Assurez-vous que tous les pods supportent votre cible de déploiement iOS

4. Effacez le cache de pod

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Puis committez le nouveau Podfile.lock

Problèmes de build Android

”Mot de passe du keystore incorrect”

Symptômes :

• Le build échoue pendant la signature
• Erreurs Gradle concernant le keystore

Solutions :

1. Vérifiez le mot de passe du keystore

   # Testez le keystore localement
   keytool -list -keystore my-release-key.keystore
   # Entrez le mot de passe lorsque demandé

2. Vérifiez les variables d’environnement

   # Assurez-vous qu'il n'y a pas d'espaces supplémentaires ou de caractères spéciaux
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. Vérifiez l’encodage base64

   # Décodez et testez
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

”Alias de clé introuvable”

Symptômes :

• La signature échoue avec une erreur d’alias

Solutions :

1. Listez les alias du keystore

   keytool -list -keystore my-release-key.keystore

2. Vérifiez que l’alias correspond exactement

   • L’alias est sensible à la casse
   • Vérifiez les fautes de frappe dans KEYSTORE_KEY_ALIAS

3. Utilisez le bon alias du keystore

   # Mettez à jour la variable d'environnement pour correspondre
   export KEYSTORE_KEY_ALIAS="le-nom-exact-de-l-alias"

”Échec du build Gradle”

Symptômes :

• Erreurs Gradle génériques
• Problèmes de compilation ou de dépendances

Solutions :

1. Testez d’abord le build localement

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Vérifiez les dépendances manquantes

   • Examinez les fichiers build.gradle
   • Assurez-vous que tous les plugins sont listés dans les dépendances

3. Vérifiez la compatibilité de la version Gradle

   # Vérifiez la version gradle
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Effacez le cache Gradle

   cd android
   ./gradlew clean
   rm -rf .gradle build

”Échec du téléversement sur le Play Store”

Symptômes :

• Le build réussit mais le téléversement échoue
• Erreurs de compte de service

Solutions :

1. Vérifiez le JSON du compte de service

   # Décodez et vérifiez le format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. Vérifiez les permissions du compte de service

   • Allez sur Play Console → Configuration → Accès API
   • Assurez-vous que le compte de service a accès à votre application
   • Accordez la permission “Publier sur les tracks de test”

3. Vérifiez que l’application est configurée dans la Play Console

   • L’application doit d’abord être créée dans la Play Console
   • Au moins un APK doit être téléversé manuellement initialement

4. Vérifiez que l’API est activée

   • L’API Google Play Developer doit être activée
   • Vérifiez dans la Google Cloud Console

Problèmes généraux

”Job introuvable” ou “Statut du build indisponible”

Symptômes :

• Impossible de vérifier le statut du build
• Erreurs d’ID de job

Solutions :

1. Attendez un moment et réessayez

   • Les jobs de build peuvent prendre quelques secondes à s’initialiser

2. Vérifiez que l’ID du job est correct

   • Vérifiez l’ID du job dans la réponse initiale du build

3. Vérifiez que le build n’a pas expiré

   • Les données de build sont disponibles pendant 24 heures

”Échec de la synchronisation du projet”

Symptômes :

• Le build échoue avant le début de la compilation
• Erreurs de fichiers manquants

Solutions :

1. Exécutez la synchronisation Capacitor localement

   npx cap sync

2. Assurez-vous que tous les fichiers natifs sont committés

   git status ios/ android/

3. Vérifiez les fichiers natifs gitignorés

   • Examinez .gitignore
   • Assurez-vous que les fichiers de configuration importants ne sont pas ignorés

”Build réussi mais je ne vois pas la sortie”

Symptômes :

• Le build affiche succès mais pas de lien de téléchargement

Solutions :

1. Vérifiez la configuration du build

   • Le stockage des artefacts peut ne pas être configuré
   • Pour la bêta publique, contactez le support concernant l’accès aux artefacts

2. Pour la soumission iOS TestFlight

   • Vérifiez App Store Connect
   • Le traitement peut prendre 5-30 minutes après le téléversement

3. Pour Android Play Store

   • Vérifiez Play Console → Tests → Tests internes
   • Le traitement peut prendre quelques minutes

Problèmes spécifiques à CI/CD

GitHub Actions : “Commande introuvable”

Symptômes :

• npx @capgo/cli échoue dans CI

Solutions :

1. Assurez-vous que Node.js est installé

   - uses: actions/setup-node@v6
     with:
       node-version: '24'

2. Installez le CLI explicitement

   - run: npm install -g @capgo/cli

GitHub Actions : “Secrets introuvables”

Symptômes :

• Les variables d’environnement sont vides dans le build

Solutions :

1. Vérifiez que les secrets sont définis

   • Allez dans Paramètres du dépôt → Secrets et variables → Actions
   • Ajoutez tous les secrets requis

2. Utilisez la syntaxe correcte

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. Vérifiez que les noms de secrets correspondent

   • Les noms sont sensibles à la casse
   • Pas de fautes de frappe dans les références de secrets

Obtenir plus d’aide

Activer les logs verbeux

# Ajoutez le flag debug (quand disponible)
npx @capgo/cli@latest build com.example.app --verbose

Collecter les informations de build

Lorsque vous contactez le support, incluez :

1. Commande de build utilisée

   npx @capgo/cli@latest build com.example.app --platform ios

2. Message d’erreur (sortie complète)

3. ID du job (depuis la sortie du build)

4. Logs de build (copiez la sortie complète du terminal)

5. Informations d’environnement

   node --version
   npm --version
   npx @capgo/cli --version

Contacter le support

• Discord : Rejoignez notre communauté
• Email : support@capgo.app
• Documentation : Docs Capgo

Limitations connues

Limitations actuelles pendant la bêta publique :

• Temps de build maximum : 10 minutes
• Taille de téléversement maximale : ~500MB
• Les builds iOS nécessitent des baux de 24 heures, le build sur Mac sera mis en file d’attente pour assurer une utilisation optimale
• Le téléchargement des artefacts de build peut ne pas être disponible

Ces limitations peuvent être ajustées en fonction des retours.

Ressources supplémentaires

• Commencer - Guide de configuration initiale
• Builds iOS - Configuration spécifique à iOS
• Builds Android - Configuration spécifique à Android
• Référence CLI - Documentation complète des commandes