Risolvere i Problemi

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

Fallimenti di costruzione

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

Sintomi:

• Il progetto di costruzione fallisce durante l'upload
• Errori di timeout dopo 60 secondi

Soluzioni:

1. Controlla la tua connessione internet

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

2. Riduci la dimensione del progetto

   • Assicurati node_modules/ non sta venendo caricato (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, ripeti il comando di build

Avviso

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

”Timeout di costruzione dopo 10 minuti”

Sintomi:

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

Soluzioni:

1. Optimizzare le dipendenze

   • Eliminare i pacchetti npm non utilizzati
   • Usa npm prune --production prima di costruire

2. Controlla le problematiche di rete durante la costruzione

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

3. Revisiona le dipendenze native

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

4. Contatta 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. Verificare che la API chiave sia corretta

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

2. Verificare i permessi della API chiave

   • La chiave deve avere write o all permessi
   • Verifica in Capgo dashboard sotto API Chiavi

3. Assicurati che la chiave API stia venendo 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:

• L'autenticazione funziona, ma si verificano errori specifici dell'applicazione

Soluzioni:

1. Verifica che l'app sia registrata

   bunx @capgo/cli@latest app list

2. Controlla 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

”Code firma fallita”

Sintomi:

• Il costrutto fallisce durante la fase di firma code
• Errori di Xcode relativi a certificati o profili

Soluzioni:

1. Verificare che il tipo di certificato corrisponda al tipo di costrutto

   • Il costrutto di sviluppo richiede certificati di sviluppo
   • Il costrutto per l'App Store richiede certificati di distribuzione

2. Verificare 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
   • Creane di nuovi nel portale dello sviluppatore Apple
   • Riaccodifica e aggiorna le variabili di ambiente

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

Sintomi:

• L'Xcode non riesce a trovare il certificato nel profilo

Soluzioni:

1. Scarica il profilo più recente da Apple

   • Vai a Apple Developer → Certificati, ID e profili
   • Scarica il profilo di provisioning
   • Assicurati che includa il tuo certificato

2. Verifica che il certificato sia nel profilo

   # 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 portal del sviluppatore di Apple, modifica il profilo
   • Assicurati di aver selezionato il certificato di distribuzione
   • Scarica e ricodifica

”Autenticazione App Store Connect fallita”

La pubblicazione su TestFlight fallisce

• Errori di chiave __CAPGO_KEEP_0__
• API key errors

Verifica le credenziali di chiave __CAPGO_KEEP_0__

1. Verify API key credentials

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

2. Sincronizza l'orologio del computer

   • L'autenticazione di App Store Connect utilizza JWT a breve scadenza generati dal tempo del sistema locale
   • Apple rifiuta i token che scadono dopo più di 20 minuti, quindi anche piccoli disallineamenti dell'orologio possono rendere un altrimenti valido token non valido
   • 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
   • Su Linux, controlla timedatectl status e abilita NTP se necessario
   • Dopo la sincronizzazione, esegui nuovamente il comando di Capgo build o credenziali

   Vedi la documentazione di Apple per Genera token per le richieste di API la regola di durata del token per App Store Connect.

3. Esegui test di API chiave localmente

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

4. Verifica le autorizzazioni della API chiave

   • La chiave richiede il ruolo 'Developer' o superiore
   • Verifica in App Store Connect -> Utenti e accessi -> Chiavi

5. Sicura che la chiave non sia revocata

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

Installazione del pod fallita

Sintomi:

• L'installazione di CocoaPods fallisce durante la costruzione.
• Error del file Podfile

Soluzioni:

1. Verifica che Podfile.lock sia stato commesso.

   git status ios/App/Podfile.lock

2. Esegui l'installazione del pod localmente

   cd ios/App
   pod install

3. Controlla per incompatibilità di pods

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

4. Cancella cache dei pods

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

Problemi di costruzione Android

”Password del keystore errata”

Sintomi:

• Il build fallisce durante la firma
• Errori di Gradle relativi alla chiave di sicurezza

Soluzioni:

1. Verifica la password della chiave di sicurezza

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

2. Verifica le variabili di ambiente

   # 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 chiave non trovato

Sintomi:

• La firma fallisce con errore di alias

Soluzioni:

1. Elenco alias del keystore

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

2. Verifica che l'alias corrisponda esattamente

   • L'alias è case-sensitive
   • Controlla per refusi nella chiave KEYSTORE_KEY_ALIAS

3. Utilizza l'alias corretto dal keystore

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

Costruzione del progetto con Gradle fallita

Sintomi:

• Error di Gradle generici
• Problemi di compilazione o di dipendenza

Soluzioni:

1. Costruisci prima un test locale

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Controlla le dipendenze mancanti

   • Verifica 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

”Fallito l'upload su Play Store”

Sintomi:

• La costruzione ha successo ma l'upload fallisce
• Error 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. Verifica i permessi dell'account di servizio

   • Vai a Play Console → Setup → API Accesso
   • Assicurati che l'account di servizio abbia accesso alla tua app
   • Concedi il permesso di "Rilascio in tracce di testing"

3. Verifica che l'app sia configurata in Play Console

   • L'app deve essere creata inizialmente in Play Console
   • Almeno un APK deve essere caricato manualmente inizialmente

4. Verifica che API sia abilitato

   • Google Play Developer API deve essere abilitato
   • 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. Attendere un momento e riprovare

   • Le attività di costruzione possono richiedere alcuni secondi per l'inizializzazione

2. Verifica che l'ID del lavoro sia corretto

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

3. Verifica che il lavoro non sia scaduto

   • Il dato di costruzione è disponibile per 24 ore

”Fallito il sincronizzazione del progetto”

Sintomi:

• La costruzione fallisce prima che inizi la compilazione
• Errori di file mancanti

Soluzioni:

1. Esegui Capacitor sincronizzazione localmente

   bunx cap sync

2. Assicurati che tutti i file nativi siano commessi

   git status ios/ android/

3. Controlla i file nativi ignorati da Git

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

”Il build è riuscito ma non vedo l'output”

Sintomi:

• Il build mostra successo ma non c'è link di download

Solutions:

1. Controlla la configurazione di costruzione

   • L'archiviazione degli artefatti potrebbe non essere configurata
   • Contatta il supporto se l'accesso agli artefatti non è disponibile per la tua build

2. Per la sottoscrizione di TestFlight per iOS

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

3. Per Play Store Android

   • Controlla Play Console → Testing → Internal testing
   • Il processo potrebbe richiedere alcuni minuti

Issue specifici del CI/CD

GitHub Actions: “Command not found”

Sintomi:

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

Soluzioni:

1. Configura Bun prima così bunx è disponibile:

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

2. Poi esegui il CLI — bunx lo recupera in modo on demand, installazione globale non necessaria:

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

GitHub Actions: “Secrets not found”

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
   • Nessun errore di ortografia nelle referenze segrete

Ottenere Maggiore Aiuto

Abilita Registro di Log Dettagliato

# 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 terminale completo)

5. Informazioni sull'ambiente

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

Contattare il Supporto

• Discord: Unisciti alla nostra community
• Email: support@capgo.app
• Documentazione: Capgo Docs

Limitazioni note

Limitazioni correnti:

• Tempo massimo di costruzione: 10 minuti
• Dimensione massima di caricamento: ~500MB
• I build iOS richiedono leasing Mac di 24 ore, costruisci su Mac per garantire l'uso ottimale
• La disponibilità del download dell'artefatto dipende dalla configurazione di destinazione e archiviazione dell'artefatto.

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

Risorse aggiuntive

• Avvio - Guida di avvio iniziale
• Costruzioni iOS - Configurazione specifica per iOS
• Costruzioni Android - Configurazione specifica per Android
• Riferimento CLI - Documentazione completa dei comandi