Dépannage

Solutions aux problèmes courants lors de la création d'applications natives avec Capgo Cloud Build.

Échecs de construction

”Échec d'envoi” ou “Délai d'expiration”

Symptômes :

• La construction faille lors de l'envoi du projet
• Erreurs de temps d'attente 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

   • S'assurer node_modules/ ne se fait pas télécharger (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 URL d'upload expirent après 1 heure
   • Si vous obtenez une erreur d'URL expirée, re-run la commande de build

Conseil

Les projets très importants peuvent atteindre la limite de temps de construction (voir Limites connues). Contactez le support pour les options d'entreprise.

”Délai de construction après 10 minutes”

Symptômes :

• La construction dépasse le temps maximum autorisé
• Statut montre timeout

Solutions :

1. Optimisez les dépendances

   • Supprimez les packages npm inutilisés
   • Utilisez npm prune --production avant de construire

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

   • Certaines dépendances peuvent télécharger des fichiers importants pendant la construction
   • Considérez la mise en cache avec un fichier de verrouillage

3. Examinez les dépendances natives

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

4. Contactez 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

« Clé API invalide » ou « Non autorisé »

Symptômes :

• La construction faille immédiatement avec une erreur d'authentification
• Erreurs 401 ou 403

Solutions :

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

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

2. Vérifiez 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 check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. Ré-authentifier

   bunx @capgo/cli@latest login

“L'application n'a pas été trouvée” ou “Aucune 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

   bunx @capgo/cli@latest app list

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

   • Vérifier capacitor.config.json __CAPGO_KEEP_0__ doit avoir accès à l'organisation de l'application
   • 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 key must have access to the app’s organization

Problèmes de construction iOS

“Code signature échouée”

Symptômes :

• La construction faille pendant la phase de signature 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. Vérifiez 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

__CAPGO_KEEP_0__

• Xcode ne peut pas trouver le certificat dans le profil

__CAPGO_KEEP_1__

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

   • Allez dans le portail du développeur Apple → Certificats, IDs et Profils
   • Télécharger le profil de provisionnement
   • Vérifiez que cela inclut votre certificat

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

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

3. Recréer le profil avec le certificat correct

   • Dans le portail du développeur Apple, éditez le profil
   • Vérifiez que votre certificat de distribution est sélectionné
   • Téléchargez et ré-encodez

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

Symptômes :

• L'envoi vers TestFlight échoue
• API clés d'erreur

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. Synchronisez l'horloge de votre ordinateur

   • L'authentification App Store Connect utilise des jetons JWT à durée de vie courte générés à partir de l'heure système locale
   • Apple rejette les jetons qui expirent dans plus de 20 minutes à l'avenir, donc même un petit dérive de l'horloge peut rendre un clé autrement valide invalide
   • Sur Windows, ouvrez Paramètres > Heure et langue > Date et heure et cliquez sur Synchroniser maintenant
   • Sur macOS, ouvrez Réglages système > Général > Date et Heure et activez la synchronisation automatique de l'heure
   • Sur Linux, vérifiez timedatectl status et activez NTP si nécessaire
   • Après synchronisation, re-exécutez la Capgo commande de build ou de credenciaux

   Voir les informations de Apple sur Génération de jetons pour les requêtes API Consultez la documentation relative à la règle de durée de vie du jeton App Store Connect.

3. Testez la clé API localement

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

4. 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

5. Assurez-vous que la clé n'est pas révoquée

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

”Pod install failed”

Symptômes :

• La construction fail pendant l'installation de CocoaPods
• Erreurs de Podfile

Solutions :

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

   git status ios/App/Podfile.lock

2. Tester l'installation de pod localement

   cd ios/App
   pod install

3. Vérifier les pods incompatibles

   • Vérifier Podfile pour les conflits de version
   • S'assurer que tous les pods supportent 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 chiffrement incorrect”

Symptômes :

• Échec de la construction pendant la signature
• Erreurs Gradle concernant le coffre fort

Solutions :

1. Vérifiez le mot de passe du coffre fort

   # 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

Clé d'alias non trouvée

Symptômes :

• L'authentification échoue avec un erreur d'alias

Solutions :

1. Lister les alias du coffre de clés

   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 la clé KEYSTORE_KEY_ALIAS

3. Utiliser la clé d'alias correcte du coffre de clés

   # 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 de poursuivre

   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ées dans les dépendances

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

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

4. Effacer le cache Gradle

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

Échec de l'upload vers le Play Store

Symptômes :

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

Solutions :

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

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

2. Vérifiez les permissions du compte de service

   • Allez dans le Console de jeu → Configuration → API Accès
   • Assurez-vous que le compte de service a accès à votre application
   • Accordez la permission « Lancer dans les pistes de test »

3. Vérifiez que l'application est configurée dans le Console de jeu

   • L'application doit être créée dans le Console de jeu avant tout
   • Au moins un APK doit être téléchargé manuellement initialement

4. Vérifiez que API est activé

   • Le API Google Play Developer doit être activé
   • Vérifiez dans le console Google Cloud

Problèmes généraux

« Job non trouvé » ou « État de construction indisponible »

Symptômes :

• Impossible de vérifier l'état de construction
• Erreurs de 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 la tâche est correct

   • Vérifiez l'ID de la tâche à partir de la réponse de construction initiale

3. Vérifiez que la tâche 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
• Les erreurs de fichiers manquants

Solutions :

1. Exécutez Capacitor synchronisation locale

   bunx cap sync

2. Vérifiez que tous les fichiers natifs sont commités

   git status ios/ android/

3. Vérifiez les fichiers gitignored natifs

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

”Le build a réussi mais je ne vois pas d’output”

Symptômes :

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

Solutions :

1. Vérifiez la configuration de construction

   • Le stockage des artefacts n'a peut-être pas été configuré
   • Contactez le support si l'accès aux artefacts 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'envoi

3. Pour le Play Store Android

   • Vérifiez Play Console → Testing → Internal testing
   • Le traitement peut prendre quelques minutes

Problèmes spécifiques CI/CD

GitHub Actions: “Command not found”

Symptômes :

• bunx @capgo/cli@latest … échoue en CI avec “commande non trouvée”

Solutions :

1. Configurez d'abord Bun alors bunx est disponible :

   - uses: oven-sh/setup-bun@v2

2. Ensuite, exécutez le CLI — bunx le récupère à la demande, aucune installation globale n'est nécessaire :

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

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 de votre 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 secrètes

Obtenir plus d'aide

Activer la journalisation détaillée

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

Collecter les informations de construction

Lorsque vous contactez le support, incluez :

1. Commande de construction utilisée

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

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

3. ID de tâche (à partir de l'output de build)

4. Journaux de build (copier l'output terminal complet)

5. Informations sur l'environnement

   node --version
   npm --version
   bunx @capgo/cli@latest --version

Contacter le Support

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

Limites connues

Limitations actuelles :

• Temps de construction maximum : 10 minutes
• Taille de téléchargement maximale : ~500MB
• Les builds iOS nécessitent des locations de Mac de 24 heures, construisez sur Mac pour enfilement afin d'optimiser l'utilisation
• La disponibilité du téléchargement de l'artefact dépend de la destination de la construction et de la configuration de stockage de l'artefact

Les limitations peuvent être ajustées en fonction des retours d'information.

Ressources supplémentaires

• Prise en main - Guide de configuration initiale
• Constructions iOS - Configuration spécifique à iOS
• Constructions Android - Configuration spécifique à Android
• CLI Référence - Documentation complète des commandes