Risolvere i Problemi

Soluzioni ai problemi comuni quando si costruiscono applicazioni native con Capgo Cloud Build.

Fallimenti di costruzione

”Fallito l'upload” o “Timeout di connessione”

Sintomi:

• Il caricamento del progetto fallisce
• I tempi di attesa superano i 60 secondi

Soluzioni:

1. Controlla la tua connessione internet

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

2. Riduci le dimensioni del progetto

   • Assicurati che node_modules/ non stia caricando (dovrebbe essere escluso automaticamente)
   • Controlla i file grandi nel tuo progetto:

   find . -type f -size +10M

3. Controlla la scadenza dell'URL di caricamento

   • Gli URL di caricamento scadono dopo 1 ora
   • Se ottieni un errore di URL scaduto, esegui nuovamente il comando di costruzione

Consiglio

I progetti molto grandi possono superare il limite di tempo di costruzione (vedi Limitazioni noteContatta il supporto per opzioni aziendali.

Timeout di costruzione dopo 10 minuti

Sintomi:

• La costruzione supera il tempo massimo consentito
• Lo stato mostra timeout

Solutions:

1. Optimizza le dipendenze

   • Elimina le dipendenze non utilizzate npm
   • Usa npm prune --production prima di costruire

2. Controlla le problematiche di rete durante la costruzione

   • Alcune dipendenze possono scaricare file di grandi dimensioni durante la costruzione
   • Considera il pre-caching con un file di blocco

3. Verifica le dipendenze native

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

4. Contattare il supporto

   • Se il tuo app ha effettivamente bisogno di più tempo
   • Possiamo regolare i limiti per casi d'uso specifici

Problemi di autenticazione

”API chiave non valida” o “Non autorizzato”

Sintomi:

• La costruzione fallisce immediatamente con un errore di autenticazione
• Errori 401 o 403

Soluzioni:

1. Verifica che la API chiave sia corretta

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

2. Verifica le autorizzazioni della chiave API

   • La chiave deve avere write o all autorizzazioni
   • Verifica nella dashboard di Capgo sotto le chiavi API

3. Assicurati che la chiave API stia essendo letta

   # 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. Riaccreditati

   bunx @capgo/cli@latest login

”L'app non è stata trovata” o “Nessuna autorizzazione per questa app”

Sintomi:

• La autenticazione funziona ma si verifica un errore specifico dell'app

Soluzioni:

1. Verifica che l'app sia registrata

   bunx @capgo/cli@latest app list

2. Verifica che l'ID dell'app corrisponda

   • Verifica capacitor.config.json appId
   • Assicurati che il comando utilizzi l'ID dell'app corretto

3. Verifica l'accesso all'organizzazione

   • Controlla di essere nell'organizzazione corretta
   • La chiave API deve avere accesso all'organizzazione dell'app

Issue di costruzione iOS

“La firma Code è fallita”

Sintomi:

• La costruzione fallisce durante la fase di firma code
• Errori di Xcode sui certificati o sui profili

Soluzioni:

1. Verifica che il tipo di certificato corrisponda al tipo di build

   • Le build di sviluppo richiedono certificati di sviluppo
   • Le build per l'App Store richiedono certificati di distribuzione

2. Controlla che il certificato e il profilo corrispondano

   # 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. Assicurati che il profilo di provisioning sia valido

   • Controlla la data di scadenza
   • Verifica che includa il tuo ID App
   • Conferma che includa il certificato

4. Regenera le credenziali

   • Cancella il vecchio certificato/profilo
   • Creare nuove in Apple Developer portal
   • Ricodificare e aggiornare le variabili di ambiente

”Il profilo di provisioning non include il certificato di firma”

Xcode non trova il certificato nel profilo

• Soluzioni:

Scaricare il profilo più recente da Apple

1. Vai a Apple Developer → Certificati, ID e Profili

   • Scaricare il profilo di provisioning
   • Assicurati che includa il tuo certificato
   • Verifica che il certificato sia nel profilo

2. Scarica il profilo di provisioning da Apple

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

3. Ricrea il profilo con il certificato corretto

   • In portallo dello sviluppatore Apple, modifica il profilo
   • Assicurati di aver selezionato il certificato di distribuzione
   • Scarica e ricodifica

”Autenticazione di App Store Connect fallita”

Sintomi:

• La pubblicazione su TestFlight fallisce
• Errori relativi alla chiave API

Soluzioni:

1. Verifica le credenziali chiave di API

   • Controlla APPLE_KEY_ID (dovrebbe essere 10 caratteri)
   • Controlla APPLE_ISSUER_ID (dovrebbe essere nel formato UUID)
   • Verifica che APPLE_KEY_CONTENT sia correttamente codificato in base64

2. Sincronizza l'orologio del computer

   • L'autenticazione di App Store Connect utilizza token JWT a breve scadenza generati dal tempo di sistema locale
   • Apple rifiuta i token che scadono dopo più di 20 minuti, quindi anche piccoli disallineamenti orari possono far fallire una chiave altrimenti valida
   • Su Windows, apri Impostazioni > Tempo e lingua > Data e ora e clicca Sincronizza ora
   • Su macOS, apri Impostazioni del sistema > Generale > Data e Ora e abilita l'orologio automatico
   • Sul sistema Linux, controlla timedatectl status e abilita NTP se necessario
   • Dopo aver sincronizzato, esegui nuovamente il comando di compilazione o di credenziali Capgo

   Vedi la documentazione di Apple per la regola di durata del token di App Store Connect. Genera i token per le richieste API Esegui il comando di verifica della chiave __CAPGO_KEEP_0__

3. Test API key locally

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

4. Verifica la chiave API localmente

   • La chiave richiede il ruolo "Developer" o un ruolo superiore
   • Verifica in App Store Connect -> Utenti e accesso -> Chiavi

5. Assicurati che la chiave non sia revocata

   • Controlla in App Store Connect
   • Genera una nuova chiave se necessario

"Installazione Pod fallita"

Sintomi:

• La compilazione fallisce durante l'installazione di CocoaPods
• Errori in Podfile

Soluzioni:

1. Verifica che Podfile.lock sia commesso

   git status ios/App/Podfile.lock

2. Testa l'installazione locale dei pod

   cd ios/App
   pod install

3. Verifica la presenza di pod incompatibili

   • Verifica Podfile per conflitti di versione
   • Assicurati che tutti i pod supportino il tuo target di distribuzione iOS

4. Pulisci il cache dei pod

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

Problemi di costruzione Android

”Keystore password incorrect”

Sezione intitolata “La password del keystore è errata””

• Sintomi:
• La costruzione fallisce durante la firma

Errori di Gradle relativi al keystore

1. Soluzioni:

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

2. Copia nel portapenne

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

3. Verifica l'encoding base64

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

”Alias della chiave non trovato”

Sintomi:

• La firma fallisce con errore di alias

Soluzioni:

1. Elenco degli alias del keystore

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

2. Verifica che l'alias corrisponda esattamente

   • L'alias è case-sensitive
   • Controlla per errori di battitura in KEYSTORE_KEY_ALIAS

3. Utilizza l'alias corretto dal keystore

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

”Errore di build Gradle”

Sintomi:

• Errori di build Gradle generici
• Issue di compilazione o di dipendenza

Soluzioni:

1. Testa la costruzione localmente per primo

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Verifica le dipendenze mancanti

   • Recensisci i file build.gradle
   • Assicurati che tutti i plugin siano elencati nelle dipendenze

3. Verifica la compatibilità della versione di Gradle

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

4. Pulisci il cache di Gradle

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

Caricamento su Play Store fallito

Sintomi:

• La build ha successo ma il caricamento fallisce
• Errori di account di servizio

Soluzioni:

1. Verifica il file JSON dell'account di servizio

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

2. Controlla i permessi dell'account di servizio

   • Vai a Play Console → Setup → API Accesso
   • Assicurati che l'account di servizio abbia accesso all'app
   • Concedi il permesso di rilascio per le tracce di testing

3. Verifica che l'app sia configurata nel Console di Play

   • L'app deve essere creata in Console di Play prima
   • Deve essere caricato almeno un APK manualmente inizialmente

4. Verifica che API sia abilitato

   • Deve essere abilitato il Google Play Developer API
   • Verifica nel Console di Google Cloud

Issue generali

'Job non trovato' o 'Stato di costruzione non disponibile'

Sintomi:

• Impossibile verificare lo stato di costruzione
• Errori di ID di lavoro

Soluzioni:

1. Aspetta un momento e riprova

   • I job di costruzione possono richiedere alcuni secondi per essere inizializzati

2. Verifica che l'ID di lavoro sia corretto

   • Verifica l'ID di lavoro dalla risposta di costruzione iniziale

3. Verifica che la costruzione non sia scaduta

   • I dati di costruzione sono disponibili per 24 ore

”Project sync failed”

Sintomi:

• Compilazione fallisce prima dell'avvio
• Errori di file mancanti

Solutions:

1. Esegui Capacitor sincronizzati localmente

   bunx cap sync

2. Assicurati che tutti i file nativi siano stati commessi

   git status ios/ android/

3. Controlla i file nativi ignorati da Git

   • Recensisci .gitignore
   • Assicurati che i file di configurazione importanti non siano ignorati

”Costruzione riuscita ma non vedo output”

Sintomi:

• La costruzione mostra successo ma non c'è link di download

Soluzioni:

1. Controlla la configurazione di costruzione

   • La memorizzazione degli artefatti potrebbe non essere configurata
   • Contatta il supporto se l'accesso agli artefatti non è disponibile per la tua costruzione

2. Per la sottoscrizione di TestFlight per iOS

   • Controlla App Store Connect
   • Il processo potrebbe richiedere 5-30 minuti dopo l'upload

3. Per la sottoscrizione di Play Store per Android

   • Verifica Console di Gioco → Test → Test interni
   • La procedura di elaborazione potrebbe richiedere alcuni minuti

Problemi specifici di CI/CD

GitHub Azioni: “Comando non trovato”

Sintomi:

• bunx @capgo/cli@latest … fallisce in CI con “comando non trovato”

Soluzioni:

1. Configura Bun prima quindi bunx è disponibile:

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

2. Eseguisci quindi il CLI — bunx lo recupera a richiesta, senza installazione globale necessaria:

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

GitHub Azioni: "Segreti non trovati"

Sintomi:

• Variabili di ambiente vuote in fase di costruzione

Soluzioni:

1. Verifica che i segreti siano impostati

   • Vai ai impostazioni del repository → Segreti e variabili → Azioni
   • Aggiungi tutti i segreti richiesti

2. Usa la sintassi corretta

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

3. Controlla che i nomi dei segreti corrispondano

   • I nomi sono case-sensitive
   • Nessi errori di ortografia nei riferimenti ai segreti

Ottenere più aiuto

Abilita registrazione dettagliata

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

Raccogli informazioni di costruzione

Quando si contatta il supporto, includere:

1. Comando di costruzione utilizzato

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

2. Messaggio di errore (output completo)

3. ID del lavoro (dal output di costruzione)

4. Log di costruzione (copia output del terminale completo)

5. Informazioni di ambiente

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

Contattare il supporto

• Discord: Unisciti alla nostra community
• Email: supporto@capgo.app
• Documentazione: Capgo Documenti

Limitazioni note

Limitazioni correnti:

• Tempo massimo di costruzione: 10 minuti
• Dimensione massima di caricamento: ~500MB
• Il caricamento dei build per iOS richiede un leasing di Mac di 24 ore, il caricamento dei build su Mac verrà messo in coda per garantire l'uso ottimale
• L'accessibilità del download degli artefatti di costruzione dipende dalla configurazione di destinazione e di archiviazione degli artefatti di costruzione

Queste limitazioni possono essere adattate in base alle informazioni di feedback.

Risorse aggiuntive

• Avvio - Guida di avvio iniziale
• Build di iOS - Configurazione specifica per iOS
• Costruzione per Android - Configurazione specifica per Android
• Riferimento CLI - Documentazione completa del comando