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 :

• Les erreurs de construction se produisent lors de l'upload du projet
• Les erreurs de temps limite 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/ n'est 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 URL d'upload expirent après 1 heure
   • Si vous obtenez une erreur d'URL expirée, ré-exécutez la commande de build

Conseil

Les projets très volumineux peuvent atteindre la limite de temps de build (voir Limites connuesContactez le support pour les options d'entreprise.

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

Symptômes :

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

Solutions :

1. Optimisez les dépendances

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

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

   • Certaines dépendances peuvent télécharger des fichiers volumineux lors de la construction
   • Considérez la mise en cache avec un fichier de verrou

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 besoin légitimement 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”

Section intitulée “” , “__CAPGO_KEEP_0__ clé invalide” ou “Non autorisé””

• Symptômes :
• La construction faille immédiatement avec une erreur d'authentification

Erreurs 401 ou 403

1. Verify API key is correct

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

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

   • La clé doit avoir write ou all permissions
   • Vérifiez la clé Capgo dans le tableau de bord API sous 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. Se réauthentifier

   bunx @capgo/cli@latest login

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

Symptômes :

• L'authentification fonctionne mais une 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 appId
   • Assurez-vous que la commande utilise l'ID de l'application correct

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

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

Problèmes de construction iOS

« La signature Code a échoué »

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 build

   • Les builds de développement nécessitent des certificats de développement
   • Les builds de 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égeneratez les informations d'identification

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

Le profil de provisionnement ne contient pas le certificat de signature

Symptômes :

• Xcode ne peut pas trouver le certificat dans le profil

Solutions :

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

   • Allez sur Apple Developer → Certificats, IDs 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

   # 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 Apple Developer, éditer le profil
   • Vérifiez que votre certificat de distribution est sélectionné
   • Télécharger et re-encoder

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

Symptômes :

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

Solutions :

1. Vérifiez les API clés de crédentials

   • 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 une clé valide
   • Sur Windows, ouvrez Paramètres > Heure et langue > Date et heure et cliquez sur Synchroniser maintenant
   • Sur macOS, ouvrez Paramètres du 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, relancez la commande de construction ou de credenciaux Capgo

   Consultez la documentation d'Apple pour la règle de durée de vie du jeton App Store Connect. Testez le jeton API localement Fenêtre de terminal

3. Test API key locally

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

4. Vérifiez les permissions du jeton API

   • La clé nécessite le rôle « Développeur » ou un niveau 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érez une nouvelle clé si nécessaire

”Pod install failed”

Symptômes :

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

Solutions :

1. Vérifiez 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 de pod

   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 journal incorrect”

Symptômes :

• La construction échoue lors de la signature
• Les erreurs de Gradle concernant la clé de journal

Solutions :

1. Vérifiez le mot de passe de la clé de journal

   # 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érifier 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 :

• L'authentification manque avec un erreur d'alias

Solutions :

1. Lister les alias du coffre-fort

   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 d'orthographe dans la clé KEYSTORE_KEY_ALIAS

3. Utilisez l'alias correct de votre clé de stockage

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

”Erreur de build Gradle”

Symptômes :

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

Solutions :

1. Testez la construction localement en premier lieu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Vérifiez les dépendances manquantes

   • Révisez 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 de Gradle

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

4. Videz 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é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 Google Play Console → Paramètres → API Accès
   • Assurez-vous que le compte de service a accès à votre application
   • Accordez la permission « Release to testing tracks »

3. Vérifiez que l'application est configurée dans le 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érifiez que API est activé

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

Problèmes généraux

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

Symptômes :

• Impossible de vérifier l'état de la construction
• Erreurs d'ID de tâche

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'est pas expirée

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

”Project sync failed”

Symptômes :

• Les compilations échouent avant le démarrage de la compilation
• Les erreurs de fichiers manquants

Solutions :

1. Exécutez Capacitor en local synchronisé

   bunx cap sync

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

   git status ios/ android/

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

   • Vérifiez .gitignore
   • Vérifiez 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 construction montre un succès mais aucun lien de téléchargement n'est disponible

Solutions :

1. Vérifiez la configuration de la construction

   • Le stockage des artefacts peut ne pas être configuré
   • Contactez le support si l'accès aux artefacts est indisponible pour votre construction

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 la Play Store Android

   • Vérifiez le console de jeu → Tests → Tests internes
   • Le traitement peut prendre quelques minutes

Problèmes spécifiques CI/CD

GitHub Actions : « Commande non trouvée »

Symptômes :

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

Solutions :

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

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

2. Exécutez ensuite le CLI — bunx il 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 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
   • Aucune faute d'orthographe dans les références aux secrets

Obtenir plus d'aide

Activer le journalisation détaillée

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

Collecter les informations de construction

Lors du contact avec 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 la sortie de construction)

4. Journaux de construction (copier la sortie complète de la fenêtre de terminal)

5. Informations d'environnement

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

Contacter le support

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

Limites connues

Limitations 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 limitations peuvent être ajustées en fonction des retours d'information.

Ressources supplémentaires

• Démarrage - Guide de configuration initiale
• Builds iOS - Configuration spécifique à iOS
• Constructions Android - Configuration spécifique à Android
• CLI Référence - Documentation complète du commande