Builds de iOS

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

Lo que aprenderás

• Aprenderás a subir tu app mediante Capgo Native build
• Aprenderás a configurar los certificados para Capgo Native Build

Requisitos

• Una cuenta de Capgo (una prueba gratuita es suficiente para empezar)
• Tu app ya registrada en Capgo (ejecuta bunx @capgo/cli@latest app add si no lo está)
• No se requiere Mac: Capgo Build compila y firma tu app de iOS en la nube, por lo que puedes ejecutar esto desde macOS, Windows o Linux
• Cuenta de Apple Developer válida ($99/año) (Debes tener permisos de administrador o propietario en la cuenta de Apple Developer)
• Tu app debe compilar correctamente (en Xcode localmente, o con Capgo Build)
• Una app de Capacitor
• Un icono configurado para la app. Las apps sin icono no se pueden subir al App Store.

Nota

Usaré la siguiente app para el tutorial: https://github.com/Cap-go/capgo-tutorial-native-build-app

Antes de empezar en los portales de Apple

Antes de configurar los certificados o lanzar tu primera subida a TestFlight, asegúrate de que la cuenta y el equipo de Apple estén listos:

• Activa la autenticación de dos factores en la cuenta de Apple usada para el registro
• Elige el tipo de membresía correcto:
  • Individual / Empresario individual: tu nombre legal personal será el nombre del vendedor en el App Store
  • Organización: requiere una entidad legal, un número D-U-N-S, un sitio web público de la empresa, un correo electrónico de trabajo en el dominio corporativo y una persona con autoridad para vincular a la organización a los acuerdos de Apple
• Usa una cuenta con acceso a Apple Developer y App Store Connect para certificados, registros de la app, claves de API y TestFlight
• Fija tu bundle ID final desde el principio. Cambiarlo después suele implicar rehacer la configuración de App Store
• Planifica estos elementos de App Store Connect antes de App Review: URL de soporte, URL de política de privacidad, clasificación por edad, capturas de pantalla, cumplimiento de exportación y datos de contacto para App Review

Nota

Referencias oficiales útiles:

• Hazte miembro del Apple Developer Program
• Envía tus apps y juegos
• Información de la versión de la plataforma en App Store Connect

Precaución

Apple actualiza regularmente su requisito mínimo de SDK. A partir de 28 de abril de 2026, las aplicaciones para iPhone y iPad subidas a App Store Connect deben compilarse con la iOS & iPadOS 26 SDK o posterior.

Recomendado: onboarding automatizado

No tienes que hacer nada de esto a mano. El onboarding de Capgo crea y configura tus credenciales de firma de iOS (certificado de distribución + perfil de aprovisionamiento) por ti: esta es la ruta recomendada:

bunx @capgo/cli@latest build init --platform ios

La siguiente guía manual es solo para quienes prefieren configurar sus propias credenciales o quieren entender exactamente qué hace Capgo internamente.

La primera build manual

Antes de plantearnos construir la app con Capgo, primero deberíamos configurarlo y hacer un primer build de TestFlight a mano. Hacer un build manual primero tiene varias ventajas:

• Configurarás el certificado de distribución en tu máquina local
• Crearás el registro en la App Store si aún no lo has hecho
• Podrás identificar cualquier problema en el proceso de build de tu app code

Antes de empezar, debes tener instalado el certificado de distribución en tu máquina local. Es un proceso algo complejo, pero te lo explicaré a continuación.

Configuración del certificado de distribución

1. Abre Xcode

2. Haz clic en Xcode -> Settings... Alternativamente, puedes usar el atajo Cmd + ,

   

3. Ve a Accounts

4. Encuentra la cuenta de Apple que está asociada a la cuenta de Apple Developer

5. Encuentra el equipo que usarás para desplegar la app

6. Haz clic en el Manage Certificates... botón

7. Asegúrate de que el certificado de distribución aparezca en la lista

8. Si no aparece, necesitas crear un certificado nuevo

   Nota

   Apple limita a 3 el número de certificados de distribución que puedes tener. Si tienes más de 3, debes eliminar uno para crear uno nuevo. No cubriré ese caso en el tutorial.

   1. Haz clic en el + botón y luego en Apple Distribution
   2. El certificado se creará automáticamente. Puedes verlo en la lista. Revisa el paso anterior para confirmar que aparece.

Ahora que tienes el certificado de distribución instalado, puedes iniciar el proceso de build.

Build manual a TestFlight

1. Abre la app en Xcode

   Ejecuta bunx cap open ios para abrir la app en Xcode.

2. Busca y haz clic en archive botón

   En la barra de herramientas de Xcode, busca y haz clic en product -> archive botón.

   

3. Espera a que la build se complete

4. Haz clic en el Distribute App botón

   

5. Selecciona TestFlight Internal Only como método de distribución y haz clic en Distribute botón

   

6. Configura el registro de la app

   Completa los siguientes campos:

   1. Nombre: el nombre de tu app, visible en la App Store
   2. SKU: el SKU de tu app; se usa para identificarla en la App Store
   3. Idioma principal: el idioma principal de tu app

   Luego, haz clic en next botón

   

7. Si la creación del registro de la app falla, cierra la ventana e intenta archivar la app de nuevo.

8. Espera a que se complete la subida

9. Si todo fue bien, deberías ver la siguiente pantalla

10. Haz clic en el Done botón

Puede que instintivamente pienses que todo está bien y que ya podrás ver tu app en TestFlight, pero aún quedan algunas cosas por terminar:

1. Añádete a TestFlight
2. Completa el cumplimiento de exportación para que el build sea testeable
3. Completa los metadatos obligatorios de App Store Connect, como la URL de soporte, la URL de la política de privacidad y la clasificación por edad
4. Prepara capturas de pantalla que coincidan con los dispositivos que realmente soportas
5. Añade los datos de contacto para la revisión de la app y las credenciales de prueba antes del envío a producción

Empecemos con la primera opción:

Añadirte a TestFlight

1. Ve a la pestaña App Store Connect página

2. Inicia sesión con tu cuenta de Apple Developer

3. Selecciona el equipo que usaste al crear el registro de la app. Si solo estás en una cuenta de desarrollador, puedes omitir este paso.

4. Haz clic en el Apps botón

5. Encuentra la app que creaste en el paso anterior y haz clic en ella

6. Haz clic en el TestFlight botón

7. Haz clic en el Internal Testers plus botón

8. Crear un nuevo grupo

   Me gusta nombrar el grupo “internal”. Puedes ponerle el nombre que quieras.

   

9. Haz clic en Invite testers botón

10. Add yourself to the group

    Búscate en la lista y selecciona la casilla junto a tu nombre. (Es posible que debas refrescar la página para verte) Luego, haz clic en el Add botón.

    

11. Verifica que te hayan añadido al grupo

    Ahora deberías aparecer en el grupo.

    

¡Felicidades! 🎉 Te has añadido a TestFlight. Ahora solo queda un último paso antes de configurar Capgo Native Build.

Configurar la información de cumplimiento

Ahora debes asegurar a Apple que tu app no utiliza ningún cifrado no estándar (como un algoritmo personalizado). Si tu app usa cifrado no estándar, te sugiero leer la documentación de Apple sobre cómo manejar esto. Hay dos formas de hacerlo:

1. Puedes hacerlo manualmente cada vez que hagas un build de tu app.
2. Puedes configurar tu archivo plist para establecer este valor automáticamente en false.

Empecemos con la primera opción:

1. Sigue todos los pasos de la sección anterior para encontrar la sección TestFlight en App Store Connect

2. Haz clic en Builds -> iOS

3. Busca el build con información de cumplimiento faltante y haz clic en Manage

4. Selecciona la opción que mejor describa tu app

   Para mí, esto es none, pero puede variar en tu caso. Después, haz clic en Guardar

   

5. Tu app ahora debería decir ready to test

   

Para la segunda opción, sigue estos pasos:

1. Abre la Info.plist archivo

2. Añade la siguiente key:

   <key>ITSAppUsesNonExemptEncryption</key>
   <false/>

3. Guardar el archivo

Nota

aquí es la documentación oficial de Apple sobre cómo informar a Apple sobre el cumplimiento de las regulaciones de exportación de cifrado.

Instalación de la app TestFlight y aceptación de la invitación

Ahora, estás CASI listo para probar tu app en TestFlight. Antes, necesitas hacer lo siguiente:

1. Descarga el App de TestFlight desde el App Store en tu dispositivo iOS/iPadOS
2. Acepta la invitación para probar tu app

Me saltaré los detalles sobre cómo instalar la app de TestFlight en tu dispositivo. Si no estás seguro de cómo instalar una app, Google tiene excelentes guías al respecto.

En cuanto a aceptar la invitación, recibirás un email de Apple con un enlace para aceptarla.

1. Abre el email de Apple con el enlace para aceptar la invitación

2. Haz clic en View in TestFlight botón

3. Haz clic en el Install botón

4. Instala la app en tu dispositivo

   Si has instalado la app previamente usando Xcode, es posible que veas la siguiente pantalla. Haz clic en el install botón.

5. Espera a que se instale la app

6. Haz clic en el Open botón y haz clic en él

¡Felicidades 🎉 Has aceptado la invitación para probar tu app en TestFlight. Ahora, puedes configurar Capgo Native Build para compilar y enviar tu app a TestFlight.

Configuración de Capgo Native Build

Hay algunas cosas que necesitas configurar en Capgo Native Build para poder compilar y enviar tu app a TestFlight. Aquí tienes una lista de las cosas que pasarás al Capgo CLI:

Parámetro	Descripción
--platform	La plataforma para la que hacer build (ios)
--apple-team-id	Tu Apple Developer Team ID (lo encuentras en Portal de Apple Developer)
--apple-key	Ruta a tu archivo de clave API de App Store Connect (.p8 archivo)
--apple-key-id	El Key ID de tu clave API de App Store Connect
--apple-issuer-id	Tu Issuer ID de App Store Connect
--certificate	Ruta a tu certificado de distribución (.p12 archivo)
--ios-provisioning-profile	Mapeo de provisioning profiles (bundleId=path o solo la ruta para un único perfil)

Comando de ejemplo:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile '/path/to/profile.mobileprovision'

ID de equipo

Empecemos por el team ID. Encontrarlo es bastante fácil.

1. Ve a Cuenta de desarrollador de Apple y desplázate hacia abajo

2. Busca el Team ID

   

Apple key, Apple key ID y Apple issuer ID

Ahora, pasemos a la clave de Apple.

macOS: deja que Capgo cree esta clave por ti

En macOS, capgo build init puede crear esta clave de API de App Store Connect por ti. Elige “No — create one for me” y se abrirá una ventana guiada de App Store Connect que te llevará paso a paso y capturará automáticamente la clave, el Key ID y el Issuer ID, sin copiar y pegar. Los pasos manuales a continuación son la alternativa (y la ruta en Windows o Linux).

1. Ve a Página de usuario y acceso de App Store Connect

   Nota

   A mí a veces el enlace no funciona. Recarga la página si no te funciona.

2. Selecciona el equipo correcto en el desplegable

   1. Haz clic en tu nombre en la esquina superior derecha
   2. Haz clic en el equipo que quieras usar

3. Haz clic en el Integrations botón

4. Busca el issuer

   Precaución

   Esto DEBE GUARDARSE - lo necesitarás más tarde

   Haz clic en el copy botón para copiar el issuer

5. Haz clic en el botón +

6. Asigna un nombre a la key y configura el acceso a App manager y haz clic en el Generate botón

7. Guarda el ID de la key

   Precaución

   Esto DEBE GUARDARSE - lo necesitarás más tarde

   

8. Descargar la clave

   Precaución

   Esto DEBE GUARDARSE - lo necesitarás más tarde

   Peligro

   NUNCA COMPARTAS LA CLAVE CON NADIE - ÚSALA SOLO EN CAPGO CLI

   

   

Felicidades 🎉 Has creado la clave de Apple, el ID de clave de Apple y el ID de emisor de Apple.

Certificado

Ahora estás listo para exportar el certificado. Como recordarás, uno de los primeros pasos de esta guía fue configurar el certificado de distribución.

Sin embargo, Apple, en su infinita sabiduría, decidió que la forma de exportar el certificado es bastante diferente a la forma en que se crean 🙃 Vamos a configurarlo:

1. Abre Acceso a llaves

   1. Haz clic Command + Space para abrir la barra de búsqueda
   2. Busca Keychain Access
   3. Haz clic en el Keychain Access app

2. Selecciona el login categoría y haz clic en la My Certificates botón

3. Busca tu certificado en la lista

   El certificado debería llamarse Apple Distribution: [Your Name/Company] (your team ID)

4. Haz clic derecho en el certificado y selecciona Export

5. Guarda el certificado como .p12 archivo

   Precaución

   Esto DEBE GUARDARSE - lo necesitarás más tarde

   1. Asegúrate de elegir un buen nombre para el archivo del certificado
   2. Asegúrate de que el formato de archivo sea Personal Information Exchange (.p12)
   3. Haz clic en el Save botón

   

6. Cuando se te pida la contraseña, puedes:

   • Omitir la contraseña (recomendado por simplicidad): Haz clic OK sin introducir ninguna contraseña
   • Establecer una contraseña: Si prefieres proteger tu certificado con una contraseña, puedes establecerla aquí. Protegidos con contraseña: .p12 los archivos son totalmente compatibles con Capgo CLI; solo indica la contraseña con la --p12-password opción al ejecutar el comando de configuración.

   

7. Cuando se te pida la “login keychain password”, introduce la contraseña que usas para iniciar sesión en tu Mac

   Introduce la contraseña con la que inicias sesión en tu Mac. Luego, haz clic en Allow botón.

   

¡Felicidades 🎉 Has exportado el certificado.

Perfil de aprovisionamiento

Ahora estás listo para exportar el perfil de aprovisionamiento. Te lo prometo, esta es la última cosa que necesitas obtener de Apple.

1. Ve a Perfiles de desarrollador de Apple

2. Selecciona el equipo correcto en el desplegable

   1. Haz clic en tu nombre en la esquina superior derecha
   2. Haz clic en el equipo que quieras usar

3. Asegúrate de estar en la página correcta Debería verse así; si no, haz clic en profiles en la barra lateral

   

4. Haz clic en el + botón

5. Selecciona el tipo de perfil Selecciona App Store Connect y haz clic en el Continue botón

   

6. Selecciona la app que quieras buildear

   Busca tu app en el desplegable y haz clic en el Continue botón

   

7. Selecciona el certificado de distribución correcto

   Selecciona el certificado que exportaste en el paso anterior y haz clic en Continue botón

   

   Si no estás seguro de qué certificado seleccionar, vuelve a Keychain Access y busca el certificado que exportaste. Luego, revisa la fecha de expiración.

   

8. Nombra el perfil

   Asigna un nombre al perfil y haz clic en Generate botón

   Consejo

   El nombre del perfil se extrae automáticamente mediante Capgo CLI; no necesitas memorizarlo.

   

9. Descargar el perfil

   Haz clic en el Download botón para descargar el perfil

   Precaución

   Este archivo DEBE GUARDARSE - lo necesitarás más tarde

   

¡Felicidades 🎉 Ahora tienes todo lo necesario para configurar Capgo Native Build.

Precaución

Nunca hagas commit de las credenciales que acabas de crear en tu repositorio. ¡Mantenlas a salvo! 🔒

Ejecutando el comando de configuración

¡Lo lograste! Ya tienes todo lo necesario para configurar Capgo Native Build.

El comando que debes ejecutar es:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --ios-provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision

Reemplaza los valores de placeholder

Reemplaza los valores de placeholder de arriba con tus credenciales reales obtenidas en los pasos anteriores:

• --apple-team-id: Tu Apple Team ID
• --apple-key: Ruta a tu archivo descargado .p8 archivo de clave
• --apple-key-id: Tu Apple Key ID
• --apple-issuer-id: Tu Apple Issuer ID
• --certificate: Ruta a tu archivo exportado .p12 certificado
• --ios-provisioning-profile: Ruta a tu archivo descargado .mobileprovision file (el bundle ID se infiere automáticamente para perfiles únicos)

Si todo salió bien, verás la siguiente salida:

Apple auth failed? Sync your clock

Si la clave API de App Store Connect parece correcta pero la autenticación sigue fallando, sincroniza el reloj de tu equipo y vuelve a intentarlo. Capgo firma el JWT de Apple con la hora local de tu sistema, y Apple rechaza los tokens que caducan a más de 20 minutos en el futuro. Un desfase de solo unos segundos puede bastar para que este paso falle.

Consulta la guía de resolución de problemas del builder para los pasos de sincronización del reloj.

Configuración de CI/CD (GitHub Actions)

Si ya has completado ID de equipo, Apple key, Apple key ID y Apple issuer ID, Certificado, y Perfil de aprovisionamiento, ya tienes todo lo necesario para CI/CD. Esta sección solo cubre cómo pasar esos valores como secretos de GitHub Actions y variables de entorno.

1) Convertir archivos de credenciales a base64 en una sola línea

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

Consejo

Los secretos de GitHub deben ser valores de una sola línea. tr -d '\n' elimina los saltos de línea de la salida base64.

2) Crear secretos del repositorio

En GitHub > Repository > Settings > Secrets and variables > Actions, añade:

Nombre del secreto	Valor
CAPGO_TOKEN	Tu token de Capgo API
APP_STORE_CONNECT_TEAM_ID	Team ID de ID de equipo
APPLE_KEY_ID	Key ID de Apple key, Apple key ID y Apple issuer ID
APPLE_ISSUER_ID	Issuer ID de Apple key, Apple key ID y Apple issuer ID
BUILD_CERTIFICATE_BASE64	Contenido de certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Generado por CLI — copiar de .capgo-credentials archivo
APPLE_KEY_CONTENT	Contenido de apple_key_base64.txt
P12_PASSWORD (opcional)	Tu .p12 contraseña si se definió al exportar

3) Usa variables de entorno en tu workflow de GitHub Actions

.github/workflows/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

Consejo

Con esta configuración, el CI envía las credenciales únicamente mediante variables de entorno. No necesitas subir los archivos de firma ni guardarlos como artifacts del workflow.

Ejecutar el build

Ahora estás listo para ejecutar tu primer build.

Ejecuta el siguiente comando para hacer el build de tu app:

bunx @capgo/cli@latest build request --platform ios

¡Felicidades! 🎉 En este punto, has hecho el build de tu app con éxito y ya está lista para enviarse a la App Store.

Enviar a revisión de la App Store

El flujo normal de build de la App Store sube el build a App Store Connect/TestFlight. Si tu release de CI también debe adjuntar el build procesado de TestFlight a la versión de la App Store y enviarlo a App Review, pasa --submit-to-store-review con un build de release:

npx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --build-mode release \
  --ios-distribution app_store \
  --submit-to-store-review \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales" \
  --no-ios-automatic-release

Esto requiere las credenciales de la clave API de App Store Connect (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, y APP_STORE_CONNECT_TEAM_ID). Carga de contraseñas de aplicación y ad_hoc la distribución no pueden enviar un build a revisión. --store-release-name es la versión de la App Store; si se omite, Capgo lee MARKETING_VERSION del proyecto de Xcode. --store-release-notes es el texto de respaldo de Novedades de App Store, y cada --store-release-notes-locale "locale=notes" entrada puede sobrescribirlo para una localización de la tienda. Usa --ios-automatic-release para lanzar automáticamente tras la aprobación de Apple, o --no-ios-automatic-release para esperar un lanzamiento manual. --ios-testflight-groups sigue disponible para la distribución beta externa, pero no es necesario para enviar a revisión de App Store.

Modo de distribución Ad-Hoc

Por defecto, Capgo compila aplicaciones iOS para distribución en la App Store (TestFlight + App Store). Si necesitas compilaciones ad-hoc en su lugar (para pruebas internas o recopilación de artefactos de CI), puedes usar el --ios-distribution repeatable.

Nota

La distribución ad-hoc es necesitas igual que la distribución Enterprise (In-House). La distribución Enterprise requiere una cuenta de Apple Developer Enterprise separada y utiliza perfiles de aprovisionamiento diferentes. Capgo actualmente admite app_store y ad_hoc solo modos.

Cuándo usar el modo ad-hoc

• Quieres distribuir IPAs directamente a dispositivos registrados (sin TestFlight)
• No tienes o no quieres usar una clave API de App Store Connect
• Quieres recopilar artefactos de build mediante --output-upload sin enviar a la App Store

Requisitos

Las builds ad-hoc tienen menos requisitos que las builds de App Store:

Credencial	¿Obligatorio?
Certificado de distribución (.p12)	Sí
Perfil de aprovisionamiento Ad-hoc (.mobileprovision)	Sí
ID de equipo ("--apple-team-id)	Sí
Clave API de App Store Connect (.p8)	No
Apple Key ID / Issuer ID	No

Nota

En ad_hoc modo, --apple-key, --apple-key-id, y --apple-issuer-id no son compatibles y se ignoran. Por eso las dos filas de App Store Connect anteriores no muestran las banderas ad-hoc CLI; estas opciones se aplican a app_store solo en modo

Precaución

Sin una clave de App Store Connect API, el autoincremento del número de build usa un fallback basado en timestamp. Para suprimir la advertencia, pasa --skip-build-number-bump.

Crear un perfil de aprovisionamiento ad-hoc

Sigue los mismos pasos que Perfil de aprovisionamiento, pero en el paso 5, selecciona Ad Hoc en lugar de App Store:

1. Ve a Perfiles de desarrollador de Apple
2. Haz clic en + botón
3. Selecciona Ad Hoc y haz clic en Continuar
4. Selecciona tu app y el certificado de distribución
5. Selecciona los dispositivos que deseas registrar
6. Nombra y descarga el perfil

Guardar las credenciales ad-hoc

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --ios-provisioning-profile './adhoc_profile.mobileprovision'

No --apple-key, --apple-key-id, o --apple-issuer-id necesario.

Ejecutar un build ad-hoc

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

Para obtener el IPA como artefacto de build, añade --output-upload:

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

CI/CD con builds ad-hoc

Para las GitHub Actions, necesitas menos secrets que en los builds de App Store:

.github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_ADHOC }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

Consejo

Ten en cuenta que APPLE_KEY_ID, APPLE_ISSUER_ID, y APPLE_KEY_CONTENT no son necesarios para builds ad-hoc.

Apps con extensiones (firma multi-target)

Si tu app incluye extensiones (extensiones de compartir, widgets, extensiones de servicio de notificaciones, etc.), cada target de extensión necesita su propio provisioning profile. Capgo lo soporta mediante el flag --ios-provisioning-profile repeatable.

Ejemplo: App + Share Extension

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile "com.example.app=./app_profile.mobileprovision" \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Cada --ios-provisioning-profile flag mapea un bundle ID a su archivo de provisioning profile. El CLI:

1. Lee cada archivo mobileprovision
2. Extrae automáticamente el nombre del perfil del plist incrustado
3. Codifica el archivo en Base64
4. Almacena todo como un único CAPGO_IOS_PROVISIONING_MAP credential

Consejo

Necesitas un certificado de distribución para todos los targets; solo los perfiles de aprovisionamiento difieren por target.

Migración desde un solo perfil

Si anteriormente usaste BUILD_PROVISION_PROFILE_BASE64 (perfil único), ejecuta:

bunx @capgo/cli@latest build credentials migrate --platform ios

Esto convierte tus credenciales actuales de perfil único al nuevo CAPGO_IOS_PROVISIONING_MAP formato y elimina las claves heredadas (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Tras la migración, añade perfiles de extensión con el update comando (fusión aditiva):

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Consejo

Usa update (no save) para añadir perfiles a credenciales existentes. El update comando fusiona los nuevos perfiles con los existentes. Usa save solo al configurar todas las credenciales desde cero.

Solución de problemas

El perfil de aprovisionamiento no incluye la capacidad XYZ.

A veces puedes ver el siguiente error:

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

Esto ocurre porque habilitaste una nueva capacidad después de crear el perfil de aprovisionamiento. El perfil de aprovisionamiento antiguo aún no incluye la nueva capacidad.

Para solucionarlo, debes regenerar el perfil de aprovisionamiento.

1. Abrir Portal de Apple Developer
2. Selecciona el equipo correcto en el desplegable
3. Haz clic en el Profiles botón
4. Busca el perfil de aprovisionamiento que quieres regenerar
5. Haz clic en el Edit botón
6. Haz clic en el Save botón
7. Haz clic en el Download botón
8. Re-run the Capgo Native Build setup command con el perfil recién descargado.

Esto debería resolver el problema.

Otros problemas

Si por cualquier razón tienes problemas con Capgo Native Build, al configurar las credenciales o al compilar la app, no dudes en contactarnos a través de nuestro soporte.

Continuar desde iOS Builds

Si estás usando Builds de iOS para planificar la automatización de CI/CD, conéctalo con CI/CD de Capgo para el flujo de trabajo del producto en Capgo CI/CD, Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds, Integraciones de Capgo para el flujo de trabajo del producto en Capgo Integraciones, Integración CI/CD para los detalles de implementación de CI/CD Integration, y Integración con GitHub Actions para los detalles de implementación de GitHub Actions Integration.