Resolución de problemas

Soluciones a problemas comunes al crear aplicaciones nativas con Capgo Cloud Build.

Fallas en la compilación

"Subida fallida" o "Tiempo de conexión agotado"

Síntomas:

• El proyecto no se puede subir correctamente.
• Errores de tiempo de espera después de 60 segundos

Soluciones:

1. Verifica tu conexión a Internet

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

2. Reducir el tamaño del proyecto

   • Asegúrate de que node_modules/ no se está subiendo (debería excluirse automáticamente)
   • Verifica la presencia de archivos grandes en tu proyecto:

   find . -type f -size +10M

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

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

Consejo

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

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

Síntomas:

• El tiempo de construcción supera el tiempo máximo permitido
• El estado muestra timeout

Soluciones:

1. Optimizar dependencias

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

2. Verifique problemas de red en 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
   • Podemos ajustar límites para casos de uso específicos

Problemas de autenticación

”La clave API es inválida” o “No autorizado”

Síntomas:

• La compilación falla de inmediato con un error de autenticación
• Errores 401 o 403

Soluciones:

1. Verificar que la clave API sea correcta

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

2. Comprobar permisos de la clave API

   • La clave debe tener write o all permisos
   • Verifique en el panel de Capgo en API Claves

3. Asegúrese de que la clave API esté siendo leída

   # 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

“La aplicación no se encontró” o “No tiene permiso para esta aplicación”

Síntomas:

• Authentication funciona pero el error específico de la aplicación

Soluciones:

1. Verificar si la aplicación está registrada

   bunx @capgo/cli@latest app list

2. Comprobar si el ID de la aplicación coincide

   • Verificar capacitor.config.json appId
   • Asegurarse de que el comando utiliza el ID de la aplicación correcto

3. Verificar acceso a la organización

   • Comprobar que se encuentra en la organización correcta
   • API debe tener acceso a la organización de la aplicación

Problemas de compilación de iOS

”Code falló el proceso de firma”

Síntomas:

• La compilación falla durante el proceso 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

   • Los builds de desarrollo necesitan certificados de desarrollo
   • Los builds 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. Asegúrese de que el perfil de provisión sea válido

   • Verifique la fecha de caducidad
   • Verifique que incluya su ID de aplicación
   • Confirme que incluye el certificado

4. Regenerar credenciales

   • Eliminar el certificado/perfil antiguo
   • Crear nuevos en el portal del desarrollador de Apple
   • Re-encodificar y actualizar 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

Solutions:

1. Descargar el perfil más reciente de Apple

   • Vaya a Apple Developer → Certificados, IDs y Perfiles
   • Descargar perfil de provisión
   • Asegúrese de que incluya su certificado

2. Verifique 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 desarrolladores de Apple, edite el perfil
   • Asegúrese de que su certificado de distribución esté seleccionado
   • Descargue y vuelva a codificar

”Falló la autenticación de App Store Connect”

Síntomas:

• La carga en TestFlight falla
• Errores de clave API

Solución:

1. Verifique las credenciales de la clave API

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

2. Syncroniza el reloj de tu computadora

   • La autenticación de App Store Connect utiliza JWTs de corta duración generados a partir del tiempo de 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 que una clave válida de lo contrario fracase
   • En Windows, abre Ajustes > Tiempo y idioma > Fecha y hora y haz clic en Sincronizar ahora
   • En macOS, abre Configuración del sistema > General > Fecha y hora y habilita el tiempo automático
   • En Linux, verifica timedatectl status y habilita NTP si es necesario
   • Después de sincronizar, vuelva a ejecutar la Capgo construcción o comando de credenciales

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

3. Pruebe la clave API localmente

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

4. Verifique los permisos de la clave API

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

5. Asegúrese de que la clave no esté revocada

   • Verifique en App Store Connect
   • Generar nueva clave si es necesario

”Falló la instalación de Pod”

Síntomas:

• La compilación falla durante la instalación de CocoaPods
• Errores en Podfile

Soluciones:

1. Verificar que Podfile.lock esté comprometido

   git status ios/App/Podfile.lock

2. Probar la instalación de pod localmente

   cd ios/App
   pod install

3. Comprobar para incompatibilidades de pods

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

4. Borrar caché de pods

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

Problemas de compilación de Android

”Contraseña de keystore incorrecta”

Síntomas:

• El proceso de compilación falla durante la firma
• Errores de Gradle sobre el almacén de claves

Solutions:

1. Verificar la contraseña del almacén de claves

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

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

No se encontró el alias de clave

Síntomas:

• La firma falla con error de alias

Solutions:

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 tecleo en KEYSTORE_KEY_ALIAS

3. Utilice el alias correcto del keystore

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

La construcción de Gradle falló

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. Verifique las dependencias faltantes

   • Revisa los archivos build.gradle
   • Asegúrate de que todas las plugins estén listadas en las dependencias

3. Verifica la compatibilidad de la versión de Gradle

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

4. Borrar caché de Gradle

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

”Falló la subida a Play Store”

Síntomas:

• El proyecto compila pero la subida falla
• Errores de cuenta de servicio

Solutions:

1. Verificar archivo JSON de cuenta de servicio

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

2. Comprobar permisos de cuenta de servicio

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

3. Comprobar si la aplicación está configurada en Play Console

   • La aplicación debe haberse creado primero en Play Console
   • Debes subir al menos un APK manualmente inicialmente

4. Verifique que API esté habilitado

   • Deberá habilitar el API de Desarrollador de Google Play
   • Verifique en la Consola de Cloud de Google

Problemas Generales

”No se encontró trabajo” o “Estado de construcción no disponible”

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 compilación pueden tardar unos segundos en inicializarse

2. Verificar que el ID de la tarea sea correcto

   • Verificar el ID de la tarea desde la respuesta de compilación inicial

3. Verificar que la tarea no ha caducado

   • Los datos de compilación están disponibles durante 24 horas

”Falló la sincronización del proyecto”

Síntomas:

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

Solución:

1. Ejecutar Capacitor sincronización local

   bunx cap sync

2. Asegúrate de que todos los archivos nativos estén comprometidos

   git status ios/ android/

3. Verifica archivos nativos ignorados en Git

   • Revisa .gitignore
   • Asegúrate de que los archivos de configuración importantes no estén ignorados

”Se ha completado la construcción, pero no veo el resultado”

Síntomas:

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

Soluciones:

1. Verifique la configuración de compilación

   • La almacenación de artefactos puede no estar configurada
   • Contacte con soporte si el acceso a artefactos no está disponible para su compilación

2. Para la presentación de iOS en TestFlight

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

3. Para 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 obtiene 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:

• Las variables de entorno están vacías en la compilación

Soluciones:

1. Verificar que los secretos estén configurados

   • Ir a la configuración de la carpeta de repositorio → Secretos y variables → Acciones
   • Agregar todos los secretos necesarios

2. Usar la sintaxis correcta

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

3. Comprobar que los nombres de los secretos coincidan

   • Los nombres son sensibles a mayúsculas y minúsculas
   • No errores de tipeo en referencias secretas

Obtener más ayuda

Habilitar depuración detallada

# 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, incluir:

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 (desde la salida de compilación)

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

5. Información de entorno

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

Contactar con Soporte

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

Limitaciones conocidas

Limitaciones actuales:

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

Estas limitaciones pueden ajustarse según la retroalimentación.

Recursos Adicionales

• Empezar - Guía de configuración inicial
• Compilación de iOS - Configuración específica de iOS
• Compilación de Android - Configuración específica de Android
• CLI Referencia - Documentación completa de comandos