Risolvere 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”

Segni distintivi:

• Build fails during project 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 le dimensioni del progetto

   • Assicurati node_modules/ non viene caricato (dovrebbe essere escluso automaticamente)
   • Check for large files in your project:

   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 costruzione

Tip

Very large projects may hit the build-time limit (see Limitazioni note. Contattare il supporto per le opzioni aziendali.

“Timeout di costruzione dopo 10 minuti”

Sintomi:

• Il build supera il tempo massimo consentito
• Lo stato mostra timeout

Soluzioni:

1. Optimizzare le dipendenze

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

2. Check for network issues in build

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

3. Recensisci 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
   • Potremmo regolare i limiti per casi d'uso specifici

Issue di autenticazione

“API chiave non valida” o “Non autorizzato”

Sintomi:

• Il build fallisce immediatamente con errore di autenticazione
• 401 o 403 errori

Soluzioni:

1. Verifica la chiave API corretta

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

2. Controlla i permessi della chiave API

   • La chiave deve avere write o all permissions
   • Controlla nel Capgo dashboard sotto API Chiavi

3. Assicurarsi che la chiave API venga 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. Riaccreditarsi

   bunx @capgo/cli@latest login

"App non trovata" o "Nessuna autorizzazione per questa app"

Sintomi:

• Authentication works but app-specific error

Soluzioni:

1. Verificare che l'app sia registrata

   bunx @capgo/cli@latest app list

2. Verifica che l'ID dell'app corrisponda

   • Verifica capacitor.config.json appId
   • Ensure command uses correct app ID

3. Verifica l'accesso all'organizzazione

   • Verifica di essere nell'organizzazione corretta
   • API deve avere accesso all'organizzazione dell'app

Problemi di costruzione per iOS

“Code la firma ha fallito”

Sintomi:

• Build fails during code signing phase
• Errori di Xcode relativi a certificati o profili

Soluzioni:

1. Verify certificate type matches build type

   • Le costruzioni di sviluppo richiedono certificati di sviluppo
   • App Store builds need Distribution certificates

2. Check certificate and profile match

   # 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. Ensure provisioning profile is valid

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

4. Regenera le credenziali

   • Elimina il vecchio certificato/profilo
   • Crea nuovi in Apple Developer portal
   • Riacoda e aggiorna le variabili di ambiente

Profilo di provisioning non include certificato di firma

Sintomi:

• Xcode non trova il certificato nel profilo

Soluzioni:

1. Scarica il profilo più recente da Apple

   • Accedi a Apple Developer → Certificati, ID e Profili
   • Scarica il profilo di provisioning
   • Assicurati che contenga il tuo certificato

2. Verifica che il certificato sia presente 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

   • Nel portale Apple Developer, modifica il profilo
   • Scegli la certificazione di distribuzione
   • Scarica e ricodifica

"Autenticazione App Store Connect fallita"

Sintomi:

• L'invio a TestFlight fallisce
• Errori chiave API

Soluzioni:

1. Verifica le credenziali della chiave API

   • Controlla APPLE_KEY_ID (dovrebbe essere 10 caratteri)
   • Controlla APPLE_ISSUER_ID (deve essere nel formato UUID)
   • Verify APPLE_KEY_CONTENT is correctly base64-encoded

2. Sincronizza l'orologio del computer

   • L'autenticazione 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 una chiave altrimenti valida non valida
   • Su Windows, apri Impostazioni > Tempo e lingua > Data e ora e clicca Aggiorna 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
   • After syncing, re-run the Capgo build or credential command

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

3. Testa la chiave API localmente

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

4. Controlla le autorizzazioni della chiave API

   • Key needs “Developer” role or higher
   • Verifica in App Store Connect -> Utenti e accessi -> Chiavi

5. Assicurati che la chiave non sia revocata

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

“Ecco, il pod install è fallito”

Sintomi:

• Build fails during CocoaPods installation
• Errori di Podfile

Soluzioni:

1. Verifica che Podfile.lock sia stato commesso

   git status ios/App/Podfile.lock

2. Testa l'installazione di pod localmente

   cd ios/App
   pod install

3. Controlla per pods incompatibili

   • Verifica Podfile per conflitti di versione
   • Ensure all pods support your iOS deployment target

4. Pulisci la cache dei pod

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

Issue di costruzione Android

“Password della chiave segreta sbagliata”

Sintomi:

• La costruzione fallisce durante la firma
• Errori di Gradle sulla chiave segreta

Soluzioni:

1. Verifica la password del keystore

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

2. Controlla 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 della chiave non trovato”

Sintomi:

• La firma fallisce con errore di alias

Soluzioni:

1. Elenco gli alias del keystore

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

2. Verifica che l'alias corrisponda esattamente

   • L'alias è case-sensitive
   • Check for typos in KEYSTORE_KEY_ALIAS

3. Utilizza l'alias corretto dal keystore

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

“La costruzione del Gradle è fallita”

Sintomi:

• Errori Gradle generici
• Issue di compilazione o di dipendenza

Soluzioni:

1. Testa la costruzione locale prima

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Controlla le dipendenze mancanti

   • Recensisci i file build.gradle
   • Ensure all plugins are listed in dependencies

3. Verify Gradle version compatibility

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

4. Pulisci cache Gradle

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

“Fallito l'upload su Play Store”

Sintomi:

• Il build ha successo ma l'upload 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. Check service account permissions

   • Go to Play Console → Setup → API Access
   • Ensure service account has access to your app
   • Concedi il permesso di rilascio per le tracce di testing

3. Verify app is set up in Play Console

   • L'app deve essere creata nella Console di Gioco prima
   • Almeno un APK deve essere caricato manualmente inizialmente

4. Verifica che API sia abilitato

   • Il Google Play Developer API deve essere abilitato
   • Verifica nella Console di Google Cloud

Problemi 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

   • Build jobs may take a few seconds to initialize

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

   • Build data is available for 24 hours

“La sincronizzazione del progetto è fallita”

Sintomi:

• Build fails before compilation starts
• Errori di file mancanti

Soluzioni:

1. Esegui Capacitor sincronizzazione localmente

   bunx cap sync

2. Assicurati di aver commesso tutti i file nativi.

   git status ios/ android/

3. Verifica file nativi ignorati da Git

   • Rivista .gitignore
   • Ensure important config files aren’t ignored

“Il build è riuscito ma non vedo l’output”

Sintomi:

• Build shows success but no download link

Soluzioni:

1. Verifica la configurazione del build

   • Artifact storage may not be configured
   • Contatta il supporto se l'accesso agli artefatti non è disponibile per la tua build

2. Per la sottoscrizione di TestFlight su iOS

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

3. Per Android Store di Google

   • Controlla Play Console → Testing → Internal testing
   • Processing may take a few minutes

La build è riuscita ma l'artefatto è sbagliato dopo un cambio di ambiente

Symptoms:

• Stato di costruzione è success ma l'IPA/AAB/APK non corrisponde alla branch o flavor che hai appena costruito
• Android AAB mancante o errato dopo aver cambiato le credenziali RC rispetto a quelle di produzione --android-flavor
• Build finishes suspiciously fast right after changing signing config or product flavor

Causa: Capgo ripristina il cache di costruzione per applicazione di default (omissione cache_key per il cache generale condiviso). Se RC e produzione condividono lo stesso ID dell'applicazione senza chiavi separate, un ripristino può riutilizzare l'output compilato dall'ambiente precedente.

Soluzioni:

1. Utilizza una chiave di cache per ambiente (consigliato per pipeline RC/PROD in corso):

   # Production
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=prod \
     --android-flavor production
   
   # Staging / RC
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=staging \
     --android-flavor staging

2. Esegui un costruzione pulita forzata quando si debugga:

   bunx @capgo/cli@latest build request com.example.app --platform android --no-cache

3. In API o integrazioni webhook, passa cache_key ad esempio "prod") o impostalo cache_enabled: false per un singolo esecuzione pulita.

Vedi Build cache per la documentazione completa delle opzioni.

Problemi Specifici per CI/CD

GitHub Azioni: “Comando non trovato”

Sintomi:

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

Soluzioni:

1. Configura Bun prima di tutto così bunx è disponibile:

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

2. Poi esegui il CLI — bunx fetches it on demand, no global install needed:

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

GitHub Azioni: "Segreti non trovati"

Sintomi:

• Variabili di ambiente vuote nella build

Soluzioni:

1. Verifica che i segreti siano impostati

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

2. Usa la sintassi corretta

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

3. Verifica che i nomi dei segreti corrispondano

   • I nomi sono case-sensitive
   • Nessun refuso nei riferimenti ai segreti

Ottenere Maggiore Aiuto

Abilita Registro Verbose

# 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 l'output del terminale completo)

5. Informazioni sull'ambiente

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

Contattare il Supporto

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

Limitazioni note

Limitazioni correnti:

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

These limitations may be adjusted based on feedback.

Il prescan ha bloccato la mia costruzione

Capgo esegue un prescan locale prescan prima del caricamento. Correggi il ritrovamento segnalato, o ignora solo quel controllo id:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

Vedi il catalogo completo: Verifica Preliminare.

Risorse Aggiuntive

• Getting Started - Guida di avvio iniziale
• Opzioni di Configurazione - CLI flag comprese --cache-key e --no-cache
• Costruzioni iOS - Configurazione specifica per iOS
• Costruzioni Android - Configurazione specifica per Android
• Verifica iniziale - Full list of pre-build checks and ignore flags
• CLI Riferimento - Documentazione completa della riga di comando