Recursos adicionales

Solutions to common issues when building native apps with Capgo Cloud Build.

Soluciones a problemas comunes al construir aplicaciones nativas con __CAPGO_KEEP_0__ Cloud Build.

”Subida fallida” o “Tiempo de conexión agotado”

Síntomas:

• La compilación falla durante la subida del proyecto
• Errores de tiempo después de 60 segundos

Soluciones:

1. Verifique su conexión a Internet

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

2. Reducir el tamaño del proyecto

   • Asegurarse node_modules/ no se está subiendo (debería estar excluido automáticamente)
   • Verifique la presencia de archivos grandes en su proyecto:

   find . -type f -size +10M

3. Verifique la expiración de la URL de subida

   • Las URL de subida caducan después de 1 hora
   • Si obtiene un error de URL caducada, vuelva a ejecutar el comando de compilación

Consejo

Los proyectos muy grandes pueden alcanzar el límite de tiempo de compilación (consulte Limitaciones conocidasContacte con el soporte para opciones de empresa.

”Tiempo de construcción después de 10 minutos””

Síntomas:

• La construcción excede el tiempo máximo permitido
• El estado muestra timeout

Soluciones:

1. Optimizar dependencias

   • Eliminar paquetes npm no utilizados
   • Usar npm prune --production antes de construir

2. Comprobar problemas de red durante la construcción

   • Algunas dependencias pueden descargar archivos grandes durante la construcción
   • Considerar la caché previa con un archivo de bloqueo

3. Revisar dependencias nativas

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

4. Contactar con soporte

   • Si su aplicación necesita legítimamente más tiempo
   • Puedemos ajustar límites para casos de uso específicos

Problemas de autenticación

"La clave API es inválida" o "No autorizado"

Síntomas:

• Fallas de construcción inmediatas con error de autenticación
• Errores 401 o 403

Solutions:

1. Verifique la clave API es correcta

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

2. Verifique los permisos de la clave API

   • La clave debe tener write o all Verifique en el panel de control __CAPGO_KEEP_0__ bajo __CAPGO_KEEP_1__ Claves
   • Check in Capgo dashboard under API Keys

3. Ensure API key is being read

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

   bunx @capgo/cli@latest login

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

Síntomas:

• La autenticación funciona pero hay un error específico de la aplicación

Soluciones:

1. Verificar que la aplicación esté registrada

   bunx @capgo/cli@latest app list

2. Comprueba que el ID de la aplicación coincida

   • Verificar capacitor.config.json appId
   • Asegúrate de que el comando utilice el ID de la aplicación correcto

3. Verificar acceso a la organización

   • Comprueba que estás en la organización correcta
   • La clave API debe tener acceso a la organización de la aplicación

Problemas de compilación de iOS

”La firma de Code falló”

Síntomas:

• El proceso de compilación falla durante la fase de firma de code
• Errores de Xcode sobre certificados o perfiles

Soluciones:

1. Verificar que el tipo de certificado coincida con el tipo de compilación

   • Las compilaciones de desarrollo necesitan certificados de desarrollo
   • Las compilaciones para la tienda de aplicaciones necesitan certificados de distribución

2. Comprobar que el certificado y el perfil coincidan

   # 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. Asegurarse de que el perfil de provisión sea válido

   • Comprobar la fecha de vencimiento
   • Verifica que incluya su ID de aplicación
   • Confirma que incluya el certificado

4. Regenera credenciales

   • Elimina el certificado/perfil antiguo
   • Crear nuevos en el portal de desarrolladores de Apple
   • Re-encode y actualiza las variables de entorno

”El perfil de provisión no incluye el certificado de firma”

Síntomas:

• Xcode no puede encontrar el certificado en el perfil

Soluciones:

1. Descarga el perfil más reciente de Apple

   • Ir a Apple Developer → Certificados, IDs y Perfiles
   • Descargar perfil de provisión
   • Asegúrate de que incluya tu certificado

2. Verificar que el certificado esté en el perfil

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

3. Recrear el perfil con el certificado correcto

   • En el portal de Apple Developer, editar perfil
   • Asegúrate de que se haya seleccionado tu certificado de distribución
   • Descargar y re-encodificar

”Autenticación de App Store Connect fallida”

Síntomas:

• La subida a TestFlight falla
• API errores de clave

Soluciones:

1. Verificar credenciales de clave API

   • Comprobar APPLE_KEY_ID (debe ser de 10 caracteres)
   • Comprobar APPLE_ISSUER_ID (debe ser formato UUID)
   • Verificar que APPLE_KEY_CONTENT esté correctamente codificado en base64

2. Sincronice el reloj de su computadora

   • La autenticación de App Store Connect utiliza JWTs de corta duración generados a partir del tiempo de su sistema local
   • Apple rechaza tokens que expiran más de 20 minutos en el futuro, por lo que incluso pequeños desfases de reloj pueden hacer fracasar una clave válida de lo contrario
   • En Windows, abra Configuración > Tiempo y idioma > Fecha y hora y haz clic Haz clic en sincronizar ahora
   • En macOS, abre Sistema de configuración > General > Fecha y hora y habilita la sincronización automática de hora
   • En Linux, verifica timedatectl status y habilita NTP si es necesario
   • Después de sincronizar, vuelve a ejecutar la Capgo construcción o comando de credenciales

   Consulta la documentación de Apple sobre Generación de tokens para solicitudes de API la regla de duración del token de App Store Connect.

3. Prueba la clave API en local

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

4. Verificar permisos de la clave API

   • La clave necesita el rol 'Desarrollador' o superior
   • Verificar en App Store Connect -> Usuarios y acceso -> Claves

5. Asegurarse de que la clave no esté revocada

   • Verificar en App Store Connect
   • Generar una nueva clave si es necesario

Falló la instalación de Pods

Síntomas:

• Los errores de construcción durante la instalación de CocoaPods
• Errores de Podfile

Soluciones:

1. Verificar que Podfile.lock se haya commitado

   git status ios/App/Podfile.lock

2. Probar la instalación de pods localmente

   cd ios/App
   pod install

3. Buscar incompatibilidades de pods

   • Revisar Podfile para conflictos de versiones
   • Asegurarse de que todos los pods soporten el destino de despliegue de iOS

4. Limpiar caché de contenedor

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

Problemas de compilación para Android

”Contraseña de keystore incorrecta”

Síntomas:

• La compilación falla durante la firma
• Errores de Gradle sobre keystore

Soluciones:

1. Verificar contraseña de keystore

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

2. Verificar variables de entorno

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

3. Verificar codificación base64

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

Error de alias de clave no encontrado

Síntomas:

• La firma falla con error de alias

Soluciónes:

1. Lista de alias del keystore

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

2. Verificar que el alias coincida exactamente

   • El alias es sensible a mayúsculas y minúsculas
   • Compruebe que no haya errores de ortografía en KEYSTORE_KEY_ALIAS

3. Utilice el alias correcto del keystore

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

”Falló la compilación de Gradle”

Síntomas:

• Errores de Gradle generales
• Problemas de compilación o dependencias

Soluciones:

1. Prueba la compilación localmente primero

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Verificar dependencias faltantes

   • Revisar archivos build.gradle
   • Asegurarse de que todas las plugins estén listadas en dependencias

3. Verificar compatibilidad de la versión de Gradle

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

4. Limpiar caché de Gradle

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

”Falló el envío a la Tienda de aplicaciones”

Síntomas:

• El build tiene éxito pero el envío falla
• Errores de cuenta de servicio

Solución:

1. Verificar JSON de cuenta de servicio

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

2. Verificar permisos de cuenta de servicio

   • Ir a la consola de Play → Configuración → Acceso API
   • Asegurarse de que la cuenta de servicio tenga acceso a tu aplicación
   • Otorgar permiso de “Lanzamiento a pistas de prueba”

3. Verificar que la aplicación esté configurada en la consola de Play

   • La aplicación debe haberse creado primero en la consola de Play
   • Debes haber subido al menos un APK manualmente inicialmente

4. Verificar que API esté habilitado

   • El API de desarrollador de Google Play debe estar habilitado
   • Verificar en la consola de Cloud de Google

Problemas generales

”Job not found” or “Build status unavailable”

Síntomas:

• No se puede verificar el estado de construcción
• Errores de ID de trabajo

Soluciones:

1. Espere un momento y vuelva a intentarlo

   • Los trabajos de construcción pueden tardar unos segundos en inicializarse

2. Verifique que el ID de trabajo sea correcto

   • Verifique el ID de trabajo desde la respuesta inicial de construcción

3. Verifique que la construcción no haya expirado

   • La información de construcción está disponible durante 24 horas

”Falló la sincronización del proyecto”

Síntomas:

• La construcción falla antes de que comience la compilación
• Errores de archivos faltantes

Soluciones:

1. Ejecutar Capacitor sincronización localmente

   bunx cap sync

2. Asegurarse de que todos los archivos nativos estén comprometidos

   git status ios/ android/

3. Verificar archivos nativos ignorados por Git

   • Revisar .gitignore
   • Asegurarse de que los archivos de configuración importantes no estén ignorados

”El proyecto se compiló con éxito pero no veo el resultado”

Síntomas:

• La compilación muestra éxito pero no hay enlace de descarga

Soluciones:

1. Verificar la configuración de la compilación

   • La almacenamiento de artefactos puede no estar configurado
   • Contactar con soporte si el acceso a los artefactos no está disponible para tu compilación

2. For iOS TestFlight submission

   • Verifique App Store Connect
   • El procesamiento puede tardar entre 5-30 minutos después de la carga

3. For Android Play Store

   • Verifique Play Console → Pruebas → Pruebas internas
   • El procesamiento puede tardar unos minutos

Problemas específicos de CI/CD

GitHub Acciones: “No se encontró el comando”

Síntomas:

• bunx @capgo/cli@latest … falla en CI con “no se encontró el comando”

Solutions:

1. Configura Bun primero entonces bunx está disponible:

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

2. Luego ejecuta el CLI — bunx lo carga a demanda, no se necesita instalación global:

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

GitHub Acciones: “No se encontraron secretos”

Síntomas:

• Variables de entorno vacías en la compilación

Soluciónes:

1. Verifique que los secretos estén configurados

   • Diríjase a la configuración de la carpeta de repositorio → Secretos y variables → Acciones
   • Agregue todos los secretos necesarios

2. Utilice la sintaxis correcta

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

3. Verifique que los nombres de los secretos coincidan

   • Los nombres son sensibles a mayúsculas y minúsculas
   • No haya errores de ortografía en las referencias a secretos

Obtenga más ayuda

Habilite el registro detallado

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

Recopilar información de compilación

Al contactar con soporte, incluya:

1. Comando de compilación utilizado

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

2. Mensaje de error (salida completa)

3. ID de tarea (de la salida de compilación)

4. Registros de compilación (copiar toda la salida del terminal)

5. Información del entorno

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

Contactar con Soporte

• Únete a nuestra comunidad: Correo electrónico
• soporte@__CAPGO_KEEP_0__.app: support@capgo.app
• Documentación: Capgo Documentación

Limitaciones conocidas

Limitaciones actuales:

• Tiempo máximo de construcción: 10 minutos
• Tamaño máximo de carga: ~500MB
• Los builds de iOS requieren arrendamientos de Mac de 24 horas, se construirá en Mac para encolar y asegurar un uso óptimo
• La disponibilidad de descarga de artefactos de construcción depende de la configuración de destino de construcción y almacenamiento de artefactos

Estas limitaciones pueden ajustarse según comentarios del usuario

Prescan bloqueó mi construcción

Ejecuta Capgo en un entorno local Prescan antes de subir. Corrija el hallazgo informado o ignora solo ese ID de verificación:

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

Ver el catálogo completo: Prescan de comprobaciones.

Recursos adicionales

• Configuración inicial - Guía de configuración inicial
• Compilación de iOS - Configuración específica de iOS
• Edición de Builds de Android - Configuración específica de Android
• Verificación de Prescan - Lista completa de verificaciones de pre-compilación y banderas de ignorancia
• CLI Referencia - Documentación completa de la orden de comando