Résoudre les problèmes

Résolutions aux problèmes courants lors de la construction d'applications natives avec Capgo Cloud Build.

Échecs de construction

”Échec d'upload” ou “Délai de connexion”

Symptômes :

• La construction faille pendant l'upload du projet
• Erreurs de timeout après 60 secondes

Solutions :

1. Vérifiez votre connexion Internet

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. Réduire la taille du projet

   • Assurez-vous que node_modules/ ne soit pas en cours d'upload (devrait être automatiquement exclu)
   • Vérifiez les fichiers volumineux dans votre projet :

   find . -type f -size +10M

3. Vérifiez l'expiration de l'URL d'upload

   • Les URLs d'upload expirent après 1 heure
   • Si vous obtenez une erreur de URL expirée, ré-exécutez la commande de build

Conseil

Les projets importants (>200MB) peuvent atteindre les limites de temps. Contactez le support pour des options d'entreprise.

“La limite de temps de build après 10 minutes”

La build dépasse le temps maximum autorisé

• L'état montre
• Solutions : timeout

Optimisez les dépendances

1. Section titled “La limite de temps de build après 10 minutes”

   • Supprimer les packages npm inutilisés
   • Utiliser npm prune --production avant la construction

2. Vérifier les problèmes de réseau lors de la construction

   • Certaines dépendances peuvent télécharger des fichiers importants pendant la construction
   • Considérer le pré-cachage avec un fichier de verrouillage

3. Réviser les dépendances natives

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. Contacter le support

   • Si votre application a légitimement besoin de plus de temps
   • Nous pouvons ajuster les limites pour des cas d'utilisation spécifiques

Problèmes d'authentification

”API key invalid” or “Unauthorized”

Symptoms:

• Clé __CAPGO_KEEP_0__ invalide
• 401 or 403 errors

Symptômes :

1. Verify API key is correct

   # Test with a simple command
   npx @capgo/cli@latest app list

2. Vérifiez que la clé API est correcte : Terminal de commande : Copier dans le presse-papier : Contrôler les permissions de la clé API

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

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

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or verify local .capgo file
   cat .capgo

4. Ré-authentifier

   npx @capgo/cli@latest login

“L'application n'a pas été trouvée” ou “Aucune permission pour cette application”

__CAPGO_KEEP_0__ :

• Le problème se produit mais l'authentification fonctionne

__CAPGO_KEEP_1__ :

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érifier capacitor.config.json appId
   • Assurez-vous que la commande utilise l'ID d'application correct

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

   • Vérifiez que vous êtes dans l'organisation correcte
   • API doit avoir accès à l'organisation de l'application

Problèmes de construction iOS

« La signature de Code a échoué »

Symptômes :

• La construction faille pendant la phase de signature de code
• Erreurs Xcode concernant les certificats ou les profils

Solutions :

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

   • Les builds de développement nécessitent des certificats de développement
   • Les builds pour l'App Store nécessitent des certificats de distribution

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

   # Decode and inspect your certificate
   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 ID d'application
   • Confirmez qu'il inclut le certificat

4. Ré-générez les informations d'identification

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

Le profil de provisionnement ne comprend pas le certificat de signature

Symptômes :

• Xcode ne peut pas trouver le certificat dans le profil

Solutions :

1. Télécharger le dernier profil depuis Apple

   • Allez sur Apple Developer → Certificats, IDs et Profils
   • Télécharger le profil de provisionnement
   • Vérifiez que le profil comprend votre certificat

2. Fenêtre de terminal

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. Recreate profile with correct certificate

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

”L'authentification App Store Connect a échoué”

Symptômes :

• L'envoi vers TestFlight échoue
• Erreurs de clé API

Solutions :

1. Vérifiez les informations de clé API

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

2. Testez la clé API localement

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

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

   • La clé nécessite le rôle « Développeur » ou un rôle 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

Section intitulée « Échec de l'installation de Pod »

Symptômes :

• L'installation échoue lors de l'installation de CocoaPods
• Erreurs de Podfile

Solutions :

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

   git status ios/App/Podfile.lock

2. Testez l'installation de pod localement

   cd ios/App
   pod install

3. Recherchez des pods incompatibles

   • Vérifiez les conflits de versions dans Podfile
   • Vérifiez que tous les pods sont compatibles avec votre cible de déploiement iOS

4. Vider le cache des pods

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Problèmes de construction Android

”Mot de passe de clé de signature incorrect”

Symptômes :

• La construction fail pendant la signature
• Erreurs de Gradle concernant la clé de signature

Solutions :

1. Vérifiez le mot de passe du coffre

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. Vérifiez les variables d'environnement

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. Vérifiez l'encodage base64

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

“Alias de clé non trouvé”

Symptômes :

• Signature échoue avec erreur d'alias

Solutions :

1. Lister les alias du coffre-fort

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

2. Vérifier que l'alias correspond exactement

   • L'alias est sensible à la casse
   • Vérifier les fautes d'orthographe dans KEYSTORE_KEY_ALIAS

3. Utiliser l'alias correct du coffre-fort

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

“Échec de la construction Gradle”

Symptômes :

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

Solutions :

1. Testez la construction locale avant tout

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Vérifiez les dépendances manquantes

   • Vérifiez les fichiers build.gradle
   • Assurez-vous que toutes les plugins soient listés dans les dépendances

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

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Vider le cache Gradle

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

Échec de l'upload sur Google Play

Symptômes :

• La construction réussit mais l'upload échoue
• Erreurs de compte de service

Solutions :

1. Vérifier le fichier JSON de compte de service

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. Vérifier les permissions de compte de service

   • Accéder à la console de Play → Configuration → API Accès
   • S'assurer que le compte de service a accès à votre application
   • Accorder la permission « Lancer vers les pistes de test »

3. Vérifier que votre application est configurée dans la console de Play

   • L'application doit être créée dans la console de Play avant tout
   • Au moins un APK doit être téléchargé manuellement initialement

4. Vérifier que API est activé

   • Le compte de développeur Google Play API doit être activé
   • Vérifier dans la console de Cloud Google

Problèmes généraux

« Emploi non trouvé » ou « Statut de construction indisponible »

Symptômes :

• Impossible de vérifier le statut de construction
• Erreurs d'ID de travail

Solutions :

1. Attendez un moment et réessayez

   • Les tâches de construction peuvent prendre quelques secondes pour s'initialiser

2. Vérifiez que l'ID de travail est correct

   • Vérifiez l'ID de travail à partir de la réponse de construction initiale

3. Vérifiez que la construction n'a pas expiré

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

”Échec de la synchronisation du projet”

Symptômes :

• La construction fail avant le début de la compilation
• Erreurs de fichiers manquants

Solutions :

1. Exécutez Capacitor synchronisation locale

   npx cap sync

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

   git status ios/ android/

3. Vérifier les fichiers natifs ignorés par Git

   • Vérifier le fichier .gitignore
   • S'assurer que les fichiers de configuration importants ne sont pas ignorés

La construction a réussi mais je ne vois pas de sortie

Symptômes :

• La solution :

Vérifier la configuration de construction

1. Le stockage des artefacts peut ne pas être configuré

   • Symptômes : La construction a réussi mais je ne vois pas de sortie
   • Contactez le support si l'accès à l'artefact n'est pas disponible pour votre build

2. Pour la soumission de TestFlight iOS

   • Vérifiez App Store Connect
   • Le traitement peut prendre entre 5 et 30 minutes après l'upload

3. Pour la boutique Play Store Android

   • Vérifiez Play Console → Testing → Test interne
   • Le traitement peut prendre quelques minutes

Problèmes spécifiques CI/CD

GitHub Actions: “Commande non trouvée”

Symptômes :

• npx @capgo/cli échoue dans CI

Solutions :

1. Vérifiez que Node.js est installé

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

2. Installez CLI explicitement

   - run: npm install -g @capgo/cli

GitHub Actions : « Secrets non trouvés »

Symptômes :

• Variables d'environnement vides lors de la construction

Solutions :

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

   • Allez dans les 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 des secrets correspondent

   • Les noms sont sensibles à la casse
   • Aucun faute d'orthographe dans les références de secret

Obtenir plus d'aide

Activer la journalisation détaillée

# Add debug flag (when available)
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 de la tâche (à partir de la sortie de build)

4. Journaux de build Afficher la sortie complète de la console

5. Informations d'environnement

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

Contacter le support

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

Limites connues

Limites actuelles :

• Durée maximale de construction : 10 minutes
• Taille maximale de téléchargement : ~500MB
• Les builds iOS nécessitent des locations de Mac de 24 heures, construire sur Mac mettra en file d'attente pour garantir un usage optimal
• La disponibilité du téléchargement des artefacts de construction dépend de la destination de construction et de la configuration de stockage des artefacts

Ces limites peuvent être ajustées sur la base des retours d'information.

Ressources supplémentaires

• Démarrage - Guide de mise en route initial
• Constructions iOS - Configuration spécifique à iOS
• Constructions Android - Configuration spécifique à Android
• CLI Référence - Documentation complète du commandement