Solucionar problemas

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

Errores de construcción

”Falló la subida” o “Tiempo de conexión agotado”

Síntomas:

• La construcción falla durante la subida del proyecto
• Timeout errors 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

   • Asegúrese de que node_modules/ no esté siendo subido (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 URLs de carga caducan después de 1 hora
   • Si obtiene un error de URL caducada, ejecute nuevamente 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 compilación supera 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. Verificar 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
   • Podemos ajustar límites para casos de uso específicos

Problemas de autenticación

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

Síntomas:

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

Soluciones:

1. Verifique que la clave API sea correcta

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

2. Verificar permisos de la clave API

   • La clave debe tener write o all permisos
   • Verifique la clave Capgo en la consola de API bajo 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

No se encontró la aplicación

Síntomas:

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

Solución:

1. Verifique que la aplicación esté registrada

   bunx @capgo/cli@latest app list

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

   • Verificar capacitor.config.json appId
   • Asegúrese 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:

• La 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 coincide con el tipo de compilación

   • Los builds de desarrollo necesitan certificados de desarrollo
   • Los builds de la Tienda de Aplicaciones necesitan certificados de distribución

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

   • Verificar la fecha de vencimiento
   • Verificar que incluya su ID de App
   • Confirmar que incluya el certificado

4. Regenerar credenciales

   • Borrar el certificado/perfil antiguo
   • Crear nuevos en el portal del desarrollador de Apple
   • Re-encode y actualizar variables de entorno

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

Síntomas:

• Xcode no puede encontrar el certificado en el perfil

Solución:

1. Descargar el perfil más reciente de Apple

   • Ir a Desarrollador de Apple → Certificados, IDs y Perfiles
   • Descargar perfil de provisión
   • Asegurarse de que incluya su 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 perfil con certificado correcto

   • En el portal de desarrolladores de Apple, editar perfil
   • Asegúrese de que su certificado de distribución esté seleccionado
   • Descargar y re-encodificar

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

Síntomas:

• Falló la subida a TestFlight
• Errores de clave API

Soluciones:

1. Verificar credenciales de clave API

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

2. Probar la clave API en local

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

3. Verificar permisos de la clave API

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

4. Asegurarse de que la clave no esté revocada

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

”Instalación de Pods fallida”

Síntomas:

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

Soluciones:

1. Verificar que Podfile.lock esté commitado

   git status ios/App/Podfile.lock

2. Probar la instalación de Pods localmente

   cd ios/App
   pod install

3. Verifique pods incompatibles

   • Revisar Podfile para conflictos de versión
   • Asegúrese de que todos los pods admitan su destino de despliegue iOS

4. Limpiar 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 del 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. Revisar 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

”Alias de clave no encontrado”

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 de construcción localmente primero

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Verifique las dependencias faltantes

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

3. Verifique la 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 Play”

Síntomas:

• El proyecto compila pero el envío falla
• Errores de cuenta de servicio

Solutions:

1. Verificar cuenta de servicio JSON

   # 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. Comprobar que API esté habilitado

   • Google Play Developer API debe estar habilitado
   • Verificar en la Consola de Cloud Google

Problemas Generales

”No se encontró el 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. Espera un momento y vuelve a intentarlo

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

2. Verificar que el ID de trabajo es correcto

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

3. Verificar que la construcción no ha expirado

   • Los datos de construcción están disponibles 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

Solución:

1. Ejecutar Capacitor sincronización local

   bunx cap sync

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

   git status ios/ android/

3. Verificar archivos nativos ignorados en Git

   • Revisar .gitignore
   • Asegúrese de que los archivos de configuración importantes no sean ignorados

”Se completó la compilación, pero no veo el resultado”

Síntomas:

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

Soluciones:

1. Verifique la configuración de compilación

   • La almacenamiento de artefactos puede no estar configurado
   • Contacte con el soporte si el acceso a los 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 “comando no encontrado”

Soluciones:

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: “Secretos no encontrados”

Síntomas:

• Variables de entorno 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 requeridos

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 hay errores de ortografía en las referencias a secretos

Obtener más ayuda

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

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

5. Información del entorno

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

Contactar con Soporte

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

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, construye 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 ser ajustadas 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