Compilaciones iOS

Compila y envía aplicaciones iOS a TestFlight y App Store usando la infraestructura Mac dedicada de Capgo.

Antes de Compilar

⚠️ Configura las Credenciales iOS Primero

Requerido: Debes guardar tus credenciales iOS antes de compilar.

Configurar Credenciales iOS →

Cómo Funcionan las Compilaciones iOS

Las compilaciones iOS se ejecutan en máquinas Mac dedicadas (Scaleway Mac minis M4) aprovisionadas bajo demanda:

Hardware: Mac minis de Apple Silicon con macOS 15
Herramienta de Compilación: Xcode con Fastlane (configuración personalizada de Capgo)
Aislamiento: Cada compilación se ejecuta como una cuenta de usuario macOS separada
Duración: Las máquinas tienen arrendamientos de 24 horas y se limpian automáticamente
Seguridad: Todos los archivos y cuentas de usuario se eliminan después de liberar la máquina

Prerequisitos

Antes de compilar para iOS, necesitas:

1. Entorno de Desarrollo

Computadora Mac con Xcode instalado (para configuración inicial de certificado)
Cuenta de desarrollador de Apple válida ($99/año)
Tu aplicación compilándose exitosamente localmente con npx cap open ios

2. Certificados de Firma de Código

Necesitarás uno de estos tipos de certificados dependiendo de tu compilación:

Tipo de Compilación	Certificado Requerido	Perfil de Aprovisionamiento
Development	Apple Development	Perfil de Desarrollo
Ad Hoc	Apple Distribution	Perfil Ad Hoc
App Store	Apple Distribution	Perfil App Store

Cómo Obtener Certificados iOS y Perfiles de Aprovisionamiento

Resumen Rápido:

Crear una Solicitud de Firma de Certificado (CSR)
- Abre Acceso a Llaveros en tu Mac
- Ve a Acceso a Llaveros → Asistente de Certificados → Solicitar un Certificado de una Autoridad Certificadora
- Ingresa tu correo electrónico y nombre, selecciona “Guardado en disco”
- Guarda el archivo .certSigningRequest
Generar Certificado en el Portal de Desarrollador de Apple
- Ve a Certificados de Desarrollador de Apple
- Haz clic en ”+” para crear un nuevo certificado
- Elige el tipo de certificado (Distribución iOS para compilaciones de App Store)
- Sube tu archivo CSR
- Descarga el certificado (archivo .cer)
Exportar Certificado como .p12
- Haz doble clic en el archivo .cer descargado para agregarlo a Llaveros
- En Acceso a Llaveros, encuentra tu certificado bajo “Mis Certificados”
- Haz clic derecho → Exportar “Apple Distribution…”
- Guarda en formato .p12 y establece una contraseña (¡guarda esta contraseña!)
Crear Perfil de Aprovisionamiento
- Ve a Perfiles de Desarrollador de Apple
- Haz clic en ”+” para crear un nuevo perfil
- Elige el tipo de perfil (App Store para compilaciones de producción)
- Selecciona tu ID de aplicación
- Selecciona el certificado que acabas de crear
- Descarga el archivo .mobileprovision

3. Clave API de App Store Connect (Recomendado)

Para envío automático a TestFlight, crea una clave API:

Ve a App Store Connect → Usuarios y Acceso → Claves
Haz clic en el botón ”+” para crear una nueva clave
Dale un nombre (ej., “Capgo CI”) y selecciona el rol “Developer”
Descarga el archivo .p8 (¡solo puedes descargarlo una vez!)
Anota el ID de Clave y el ID de Emisor

Configuración de Compilación

Variables de Entorno Requeridas

Configura estas credenciales antes de compilar:

# Firma iOS (Requerido)
BUILD_CERTIFICATE_BASE64="<certificado-p12-codificado-en-base64>"
BUILD_PROVISION_PROFILE_BASE64="<mobileprovision-codificado-en-base64>"
P12_PASSWORD="<contraseña-de-certificado>"

# API de App Store Connect (para envío)
APPLE_KEY_ID="ABC1234567"
APPLE_ISSUER_ID="00000000-0000-0000-0000-000000000000"
APPLE_KEY_CONTENT="<clave-p8-codificada-en-base64>"

# Configuración Adicional
APP_STORE_CONNECT_TEAM_ID="1234567890"
APPLE_PROFILE_NAME="App Store com.example.app"

Generando Credenciales en Base64

Certificado (.p12):

base64 -i TuCertificado.p12 | pbcopy

Perfil de Aprovisionamiento (.mobileprovision):

base64 -i TuPerfil.mobileprovision | pbcopy

Clave de App Store Connect (.p8):

base64 -i AuthKey_ABC1234567.p8 | pbcopy

La cadena base64 ahora está en tu portapapeles - pégala en tu variable de entorno o secretos de CI/CD.

Compilando para iOS

Compilación de Debug (Development)

npx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode debug

Esto crea una compilación de desarrollo que se puede instalar en dispositivos registrados.

Compilación de Release (App Store)

npx @capgo/cli@latest build com.example.app \
  --platform ios \
  --build-mode release

Esto crea una compilación de App Store y automáticamente la envía a TestFlight si tienes configuradas las credenciales de la API de App Store Connect.

Integración CI/CD

Ejemplo de GitHub Actions

name: Build iOS App

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'

      - name: Install dependencies
        run: npm ci

      - name: Build web assets
        run: npm run build

      - name: Sync Capacitor
        run: npx cap sync ios

      - name: Build iOS app
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.IOS_PROVISION_PROFILE }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.TEAM_ID }}
        run: |
          npx @capgo/cli@latest build ${{ secrets.APP_ID }} \
            --platform ios \
            --build-mode release

Detalles del Proceso de Compilación

Qué Sucede Durante una Compilación iOS

Aprovisionamiento de Máquina (1-2 minutos)
- Se aprovisiona o asigna un Mac mini de Scaleway
- macOS 15 con Xcode preinstalado
- Se ejecutan scripts de arranque (si es el primer uso)
Aislamiento de Usuario (~10 segundos)
- Se crea usuario macOS único: job-<jobId>
- Directorio home dedicado: /Users/job-<jobId>
- Se crea espacio de trabajo aislado
Configuración de Proyecto (~30 segundos)
- Zip del proyecto descargado desde R2
- Extraído al espacio de trabajo
- Credenciales inyectadas como variables de entorno
Compilación Fastlane (3-8 minutos)
- Llavero creado con certificado de firma
- Perfil de aprovisionamiento instalado
- Comando de compilación Xcode ejecutado
- Archivo IPA generado
Envío a App Store (1-2 minutos, si está configurado)
- IPA subido a App Store Connect
- Enviado a TestFlight
- El procesamiento comienza del lado de Apple
Limpieza (inmediata)
- Cuenta de usuario eliminada y destruida
- Archivos del espacio de trabajo eliminados
- Archivos temporales borrados
Liberación de Máquina (después de 24 horas)
- La máquina Mac es destruida
- Todos los datos eliminados permanentemente

Pila de Compilación

Nuestro entorno de compilación iOS incluye:

macOS: 15 (última versión estable)
Xcode: Última versión estable
Fastlane: Última versión estable
CocoaPods: Última versión estable
Node.js: 18.x (LTS)
Ruby: Ruby del sistema con bundler

Tiempos de Compilación

Tiempos típicos de compilación iOS:

Tipo de Compilación	Primera Compilación	Compilaciones Subsecuentes*
Debug	5-7 minutos	4-6 minutos
Release	7-10 minutos	5-8 minutos

*Las compilaciones subsecuentes pueden ser más rápidas si se reutiliza la misma máquina dentro de la ventana de 24 horas.

Solución de Problemas

Problemas Comunes

“Firma de código falló”

Verifica que tu certificado sea para el tipo de distribución correcto
Asegúrate de que el perfil de aprovisionamiento coincida con tu ID de aplicación
Verifica que P12_PASSWORD sea correcta

“El perfil de aprovisionamiento no incluye el certificado de firma”

Regenera tu perfil de aprovisionamiento incluyendo el certificado
Vuelve a descargar y vuelve a codificar el perfil

“Autenticación de App Store Connect falló”

Verifica APPLE_KEY_ID, APPLE_ISSUER_ID y APPLE_KEY_CONTENT
Asegúrate de que la clave API no haya sido revocada
Verifica que la clave tenga el rol “Developer” o superior

“Tiempo de espera de compilación agotado después de 10 minutos”

Verifica si tu aplicación tiene dependencias nativas grandes
Considera optimizar tu Podfile
Contacta soporte si las compilaciones consistentemente agotan el tiempo

Registros de Debug

Todos los registros de compilación se transmiten en tiempo real. Busca estas fases clave:

✔ Máquina asignada: m-abc123
→ Creando usuario: job-abc123
→ Instalando dependencias CocoaPods...
→ Compilando aplicación iOS...
→ Firmando código con certificado...
→ Subiendo a App Store Connect...
✔ Compilación exitosa

Si una compilación falla, el error se mostrará claramente en los registros con el mensaje de error específico de Fastlane/Xcode.

Mejores Prácticas

1. Probar Localmente Primero

Siempre asegúrate de que tu compilación iOS funcione localmente antes de usar la compilación en la nube:

npx cap open ios
# Compilar en Xcode

2. Usar Variables de Entorno

Nunca confirmes certificados o claves en tu repositorio. Siempre usa:

Secretos de CI/CD (GitHub, GitLab)
Variables de entorno
Gestión de secretos segura

3. Cachear Dependencias

Para compilaciones más rápidas, asegúrate de que tu package.json y Podfile.lock estén confirmados en control de versiones.

4. Monitorear Tiempo de Compilación

Mantén un ojo en la duración de la compilación para optimizar costos:

# El CLI muestra el tiempo de compilación al final
Compilación exitosa en 6m 42s (13.4 minutos de facturación a tarifa 2×)

Próximos Pasos

Compilaciones Android - Configurar compilaciones Android
Solución de problemas - Problemas comunes de compilación
Referencia CLI - Documentación completa de comandos