Risolvere Problemi

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

Fallimenti di costruzione

”Sono fallito l'upload” o “Timeout di connessione”

Segni distintivi:

• La costruzione fallisce durante l'upload del progetto
• 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 viene caricato (dovrebbe essere escluso automaticamente)
   • Controlla la presenza di 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

Suggerimento

I progetti molto grandi possono superare il limite di tempo di build (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

Soluzioni:

1. Optimizza le dipendenze

   • Elimina i pacchetti npm non utilizzati
   • Utilizza 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
   • Considerare il pre-caching con un file di blocco

3. Revisionare 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 adattare i limiti per casi d'uso specifici

Issue di autenticazione

”API key invalid” or “Unauthorized”

Sezione intitolata ""__CAPGO_KEEP_0__ chiave non valida" o "Non autorizzato""

• Costruisce fallisce immediatamente con errore di autenticazione
• 401 o 403 errori

Soluzioni:

1. Verifica che la chiave API sia corretta

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

2. Controlla le autorizzazioni della chiave API

   • La chiave deve avere write o all Verifica che la chiave __CAPGO_KEEP_0__ sia letta correttamente
   • Verifica in dashboard Capgo sotto API Chiavi

3. Assicurati che la chiave API sia letta correttamente

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

   bunx @capgo/cli@latest login

”App not found” or “No permission for this app”

Sintomi:

• L'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

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

Problemi di costruzione per iOS

”Code signing failed”

Sintomi:

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

Soluzioni:

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

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

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

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

4. Regenera le credenziali

   • Elimina il vecchio certificato/profilo
   • Crea nuove credenziali nel portale dello sviluppatore Apple
   • Ricodifica e aggiorna le variabili di ambiente

Profilo di provisioning non include il certificato di firma

Sintomi:

• 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 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 di Apple Developer, modifica il profilo
   • Assicurati di aver selezionato il tuo certificato di distribuzione
   • Scarica e ricodifica

”Autenticazione App Store Connect fallita”

Sintomi:

• L'upload su TestFlight fallisce
• Errori di chiave API

Soluzioni:

1. Verifica le credenziali di chiave API

   • Controlla APPLE_KEY_ID (dovrebbe essere di 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 del sistema locale
   • Apple rifiuta i token che scadranno dopo più di 20 minuti, quindi anche piccoli disallineamenti dell'orologio possono far fallire una chiave altrimenti valida
   • Su Windows, apri Impostazioni > Tempo e lingua > Data e ora e cliccare 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 aver sincronizzato, ripeti la costruzione o la richiesta di credenziali Capgo

   Vedi la documentazione di Apple per Generazione di token per richieste API la regola di durata del token per l'accesso all'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. Verifica i permessi della chiave API

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

5. Assicurati che la chiave non sia revocata

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

”Installazione Pod fallita”

Sintomi:

• I problemi di costruzione si verificano durante l'installazione di CocoaPods
• Errori in 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
   • Assicurati che tutti i pods supportino il tuo target di distribuzione iOS

4. Cancella cache del pod

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

Problemi di costruzione per Android

”Keystore password incorrect”

Sezione intitolata “”Password della chiave di sicurezza errata””

• Sintomi:
• La costruzione fallisce durante la firma

Errori di Gradle sulla chiave di sicurezza

1. Soluzioni:  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

Chiave alias non trovata

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 di non aver commesso errori di ortografia in KEYSTORE_KEY_ALIAS

3. Utilizza l'alias corretto dal keystore

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

”Esecuzione del build di Gradle fallita”

Sintomi:

• Errori Gradle generici
• Problemi di compilazione o di dipendenze

Soluzioni:

1. Esegui prima una costruzione 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 cache Gradle

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

”Errore di caricamento su Play Store”

Sintomi:

• La costruzione 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. Verifica le autorizzazioni dell'account del servizio

   • Vai a Console di Gioco → Configurazione → API Accesso
   • Assicurati che l'account del servizio abbia accesso alla tua app
   • Concedi la

3. Rilascio ai percorsi di testing

   • Verifica che l'app sia configurata nella Console di Gioco
   • L'app deve essere creata nella Console di Gioco prima

4. Check API is enabled

   • Verifica che API sia abilitato
   • Il Google Play Developer __CAPGO_KEEP_0__ deve essere abilitato

Verifica nella Console di Google Cloud

”Non trovato il lavoro” o “Stato di costruzione non disponibile”

Sintomi:

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

Soluzioni:

1. Attendere un momento e riprovare

   • Il lavoro di costruzione potrebbe richiedere alcuni secondi per inizializzare

2. Verificare che l'ID del lavoro sia corretto

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

3. Verificare che la costruzione non sia scaduta

   • I dati di costruzione sono disponibili per 24 ore

”Fallito il sincronizzazione del progetto”

Sintomi:

• Il 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 stati commessi

   git status ios/ android/

3. Controlla i file nativi ignorati dal Git

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

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

Sintomi:

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

Soluzioni:

1. Controlla la configurazione della build

   • 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 di iOS

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

3. Per il Play Store Android

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

Issue 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 così bunx è disponibile:

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

2. Esegui poi il comando CLI — bunx lo carica a richiesta, non è necessaria l'installazione globale:

   - 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. Utilizza 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 nelle referenze ai segreti

Ottenere Maggiore Aiuto

Abilita la registrazione dettagliata

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

Raccogli informazioni di costruzione

Quando contatti il supporto, includi:

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 (dalla output di costruzione)

4. Log dei build (copia tutta l'output del terminale)

5. Informazioni sull'ambiente

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

Contattare il Supporto

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

Limitazioni note

Limitazioni correnti:

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

Queste limitazioni possono essere aggiustate in base alle risposte dei clienti.

Prescan ha bloccato la mia costruzione

Capgo esegue un prescan locale prescan Esegue un prescan locale prima dell'upload. Correggi il problema 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: I controlli del prescan.

Risorse aggiuntive

• Avvio rapido - Guida di avvio rapido
• Costruzioni iOS - Configurazione specifica per iOS
• Costruzioni Android - Configurazione specifica per Android
• Verifiche di prescan - Elenco completo delle verifiche pre-costruzione e delle flag di ignorazione
• CLI Riferimento - Documentazione completa del comando