iOS Builds

Construya y envíe aplicaciones iOS a TestFlight y la Tienda de Aplicaciones utilizando la infraestructura Mac dedicada de Capgo.

Lo que aprenderás

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

Requisitos previos

• Una cuenta de Capgo (un período de prueba gratuito es suficiente para empezar)
• Tu aplicación ya registrada en Capgo (corre bunx @capgo/cli@latest app add Si no)
• No se requiere Mac: Capgo Build compila y firma tu aplicación iOS en la nube, por lo que puedes ejecutar esto desde macOS, Windows o Linux
• Cuenta de desarrollador de Apple válida ($99/año) (Debes tener derechos de administrador o propietario en la cuenta de desarrollador de Apple)
• Tu aplicación debe compilar con éxito (en Xcode localmente, o con Capgo Build)
• Una aplicación Capacitor
• Un icono configurado para la aplicación. Las aplicaciones sin icono no pueden subirse a la Tienda de Aplicaciones

Nota

Usaré la siguiente aplicación para el tutorial: https://github.com/Cap-go/capgo-tutorial-de-construcción-nativa-de-aplicación

Antes de empezar en los portales de Apple

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

• Activar la autenticación en dos factores para la cuenta de Apple utilizada para el registro
• Elija el tipo de membresía adecuado:
  • Individualista / Propietario únicoTu nombre personal se convierte en el nombre del vendedor en la Tienda de Aplicaciones.
  • Organización: requiere una entidad legal, un número D-U-N-S, un sitio web de empresa público, un correo electrónico de trabajo en el dominio de la empresa y una persona con autoridad para vincular a la organización a los acuerdos de Apple
• Utilice una cuenta que pueda acceder a Apple Developer y App Store Connect para certificados, registros de aplicaciones, API claves y TestFlight
• Consolide su ID de paquete final temprano. Cambiarlo más tarde suele significar volver a configurar la Tienda de Aplicaciones
• Plan these App Store Connect items before App Review: support URL, privacy policy URL, age rating, screenshots, export compliance, and App Review contact details

Nota

Referencias oficiales útiles:

• Convertirse en miembro del programa de desarrolladores de Apple
• Envíe sus aplicaciones y juegos
• Información de versión de la plataforma en App Store Connect

Advertencia

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

Recomendado: onboarding automático

No necesitas hacer nada de esto a mano. Capgo crea y configura tus credenciales de firma de iOS (certificado de distribución + perfil de configuración) por ti — este es el camino recomendado:

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

El recorrido manual a continuación solo es para aquellos que prefieren configurar las credenciales ellos mismos, o quieren entender exactamente qué hace Capgo debajo de la cubierta.

La primera construcción manual

Antes de que podamos empezar a pensar en construir la aplicación con Capgo, debemos configurarla primero, y hacer una primera construcción de TestFlight a mano. Hay algunas ventajas en hacer una construcción manual primero:

• Configurarás el certificado de distribución en tu máquina local
• Crearás el registro de la Tienda de Mac si no lo has hecho aún
• Podrá resolver cualquier problema con el proceso de compilación relacionado con su aplicación code.

Antes de comenzar, debe tener instalado el certificado de distribución en su máquina local. Esto es bastante complejo, pero lo explicaré a continuación.

Configuración del certificado de distribución

1. Abrir Xcode

2. Haga clic en Xcode -> Settings... Alternativamente, puede utilizar el atajo Cmd + ,

   

3. Ir a Accounts

4. Encuentre la cuenta de Apple Account agregada a la cuenta de desarrollador de Apple.

5. Encuentre el equipo que utilizará para desplegar la aplicación

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

7. Asegúrese de que pueda ver el certificado de distribución en la lista

8. Si no lo ve, necesita crear un nuevo certificado

   Nota

   Apple limita el número de certificados de distribución que puede tener a 3. Si tiene más de 3 certificados, necesita eliminar uno para crear uno nuevo. No cubriré esto en el tutorial.

   1. Haga clic en el + y luego haga clic en Apple Distribution
   2. El certificado se creará automáticamente. Puede verlo en la lista. Mire el paso anterior para confirmar que lo vea.

Ahora que tienes instalado el certificado de distribución, puedes comenzar el proceso de compilación.

Compilación manual para TestFlight

1. Abre la aplicación en Xcode

   Ejecutar bunx cap open ios Abrir la aplicación en Xcode.

2. para abrir la aplicación en Xcode. archive button

   In the Xcode toolbar, find and click on the product -> archive button.

   

3. Espera a que se complete la compilación

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 aplicación

   Rellena los siguientes campos:

   1. Nombre: El nombre de tu aplicación - visible en la Tienda de Mac App
   2. SKU - el código SKU de tu aplicación - se utiliza para identificar tu aplicación en la Tienda de Mac App Store
   3. El idioma principal - el idioma principal de tu aplicación

   Entonces, haz clic en el next botón

   

7. Si falla la creación del registro de la aplicación, intenta cerrar la ventana y intenta archivar la aplicación de nuevo.

8. Espera a que la subida se complete

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

10. Haz clic en el Done botón

Es posible que pienses que todo está bien ahora y que podrás ver tu aplicación en TestFlight ahora, pero hay un par de cosas más que aún debes terminar:

1. Add yourself to TestFlight
2. Cumplir con los requisitos de exportación para que la compilación sea verificable
3. Rellena los metadatos obligatorios de App Store Connect, como tu URL de soporte, política de privacidad y clasificación de edad
4. Prepara capturas de pantalla que coincidan con los dispositivos que realmente soportas
5. Agregar detalles de contacto de revisión de aplicación y cualquier credencial de prueba antes de la presentación de producción

Empecemos con el primero:

Agregarse a TestFlight

1. Vaya a la App Store Connect page

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

3. Selecciona el equipo que utilizaste cuando creaste el registro de la aplicación. Si solo tienes una cuenta de desarrollador, puedes saltarte este paso.

4. Haga clic en el Apps botón

5. Encuentra la aplicación que creaste en el paso anterior y haz clic en ella

6. Haga clic en el TestFlight botón

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

8. Crear un nuevo grupo

   Me gusta llamar al grupo “internos”. Puedes llamarlo como desees.

   

9. Haga clic en Invite testers botón

10. Agregarse a sí mismo al grupo

    Encuentre su nombre en la lista y seleccione la casilla al lado de su nombre. (Puede que deba refrescar la página para verlo) Luego, haga clic en el Add botón.

    

11. Verifica que estás agregado al grupo

    Ahora deberías verte en el grupo.

    

Felicidades 🎉 Has agregado a ti mismo a TestFlight. Ahora solo queda una cosa más que debes hacer antes de que puedas configurar Capgo Native Build.

Configurando la información de cumplimiento

Ahora necesitas prometer a Apple que tu aplicación no utiliza ninguna criptografía no estándar (como un algoritmo personalizado). Si tu aplicación utiliza alguna criptografía no estándar, te recomiendo leer la documentación de Apple en cómo manejar esto. Hay dos formas de hacer esto:

1. Puedes hacer esto a mano cada vez que construyas tu aplicación.
2. Puedes configurar tu archivo plist para establecer automáticamente este valor en false.

Empecemos con la primera opción:

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

2. Sobre Builds -> iOS

3. Encuentre la compilación con información de conformidad faltante y haga clic en Manage

4. Seleccione la opción que mejor describa su aplicación

   Para mí, esto es nonepero puede ser diferente para ti. Después, haga clic en guardar

   

5. Su aplicación debería decir ahora ready to test

   

En cuanto al segundo, aquí están los pasos:

1. Abrir el Info.plist archivo

2. Agregar la siguiente clave:

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

3. Guardar el archivo

Nota

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

Instalar la aplicación TestFlight y aceptar la invitación

Ahora, usted está LISTO Pronto para probar su aplicación en TestFlight. Antes, necesita hacer las siguientes cosas:

1. Descargar la aplicación de TestFlight desde la Tienda de App en su dispositivo iOS/iPadOS
2. Aceptar la invitación para probar su aplicación

No detallaré cómo instalar la aplicación de TestFlight en su dispositivo. Si no está seguro de cómo instalar una aplicación, Google tiene algunas grandes guías sobre cómo hacerlo.

En cuanto a aceptar la invitación, recibirá un correo electrónico de Apple con un enlace para aceptar la invitación.

1. Abrir el correo electrónico de Apple con el enlace para aceptar la invitación

2. Hacer clic en View in TestFlight botón

3. Haz clic en el Install botón

4. Instala la aplicación en tu dispositivo

   Si has instalado la aplicación previamente utilizando Xcode, es posible que veas la siguiente pantalla. Por favor, haz clic en el install botón.

5. Espera a que se instale la aplicación

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

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

Configurando Capgo Native Build

Existen algunas cosas que debes configurar en Capgo Build Nativo para poder compilar y enviar tu aplicación a TestFlight. Aquí tienes una lista de las cosas que pasarás al Capgo CLI:

Parámetro	Descripción
--platform	La plataforma para compilar (ios)
--apple-team-id	Tú ID de equipo de desarrollador de Apple (encontrado en Portal de Desarrollador de Apple)
--apple-key	Ruta a tu archivo de API Key de App Store Connect (.p8 archivo)
--apple-key-id	La clave ID de su App Store Connect API clave
--apple-issuer-id	Tú ID de emisor de App Store Connect
--certificate	Ruta a tu certificado de distribución (.p12 archivo)
--ios-provisioning-profile	Provisionamiento de perfil de mapa (bundleId=path o simplemente ruta para un perfil único)

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

Comencemos con el ID del equipo. Encontrarlo es bastante sencillo.

1. Vaya a Cuenta de Desarrollador de Apple y desplázate hacia abajo

2. Encuentre la Team ID

   

Apple key, ID de clave Apple y ID de emisor Apple

Ahora, pasemos a la clave Apple.

macOS: ¡deje que Capgo cree esta clave para usted!

En macOS, capgo build init puede crear esta clave de App Store Connect API para usted. Elija ‘No — cree una para mí’ y una ventana guiada se abre en App Store Connect, lo guía a través de cada paso y captura la clave, el ID de clave y el ID de emisor automáticamente — sin copiar y pegar. Los pasos manuales a continuación son la alternativa (y el camino en Windows o Linux).

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

   Nota

   Para mí, el enlace a veces no funciona. Recarga la página si no funciona para ti.

2. Seleccionar el equipo correcto en el menú desplegable

   1. Hacer clic en tu nombre en la esquina superior derecha
   2. Hacer clic en el equipo que deseas utilizar

3. Hacer clic en el Integrations botón

4. Encuentra el issuer

   Cuidado

   Este DEBE SER GUARDADO - lo necesitarás más tarde

   Haga clic en el copy botón para copiar el emisor

5. Haga clic en el botón con signo más

6. Establezca el nombre de la clave y establezca el acceso a App manager y haga clic en el Generate botón

7. Guardar el ID de clave

   Advertencia

   Este ES PARA GUARDAR - lo necesitarás más tarde

   

8. Descargar la clave

   Advertencia

   Este DEBE SER GUARDADO - lo necesitarás más tarde

   Peligro

   NUNCA COMPARTAS LA LLAVE CON NADIE - ÚSALA SOLO EN EL 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 en que exportas el certificado es bastante diferente de la forma en que los creas 😂 Vamos a ver cómo configurarlo:

1. Abrir Acceso a la Caja de Llaves

   1. Hacer clic Command + Space para abrir la barra de búsqueda
   2. Buscar por Keychain Access
   3. Hacer clic en el Keychain Access aplicación

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

3. Encuentre su certificado en la lista

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

4. Haga clic derecho en el certificado y seleccione Export

5. Guardar el certificado como un .p12 archivo

   Advertencia

   Esto DEBE SER GUARDADO - lo necesitará más tarde

   1. Asegúrese de seleccionar un buen nombre para el archivo de certificado
   2. Make sure the file format is set to Personal Information Exchange (.p12)
   3. Haga clic en el Save botón

   

6. Cuando se le pregunte por la contraseña, puede elegir:

   • Saltar la contraseña (recomendado por simplicidad): Haga clic OK sin ingresar una contraseña
   • Establecer una contraseña: Si prefieres proteger tu certificado con una contraseña, puedes establecerla aquí. Protegido con contraseña .p12 archivos están completamente soportados por el Capgo CLI - solo proporciona la contraseña utilizando el --p12-password opción al ejecutar el comando de configuración.

   

7. Cuando se le pida la "contraseña de la llave de inicio de sesión", ingrese la contraseña que utiliza para iniciar sesión en su Mac.

   Proporcione la contraseña que utiliza para iniciar sesión en su Mac. Luego, haga clic en el Allow botón.

   

¡Felicidades! Ha exportado el certificado.

Perfil de configuración

Ahora, está listo para exportar el perfil de provisión. Te prometo, esto es la última cosa que necesitarás obtener de Apple.

1. Vaya a Perfiles de Desarrollador de Apple

2. Haga clic en su nombre en la esquina superior derecha

   1. Haz clic en tu nombre en la esquina superior derecha
   2. Haz clic en el equipo que deseas utilizar

3. Asegúrate de estar en la página correcta Debería verse así, si no haz clic en profiles en el menú 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. Seleccione la aplicación que desea construir

   Encuentre su aplicación en el menú desplegable y haga clic en el Continue botón

   

7. Seleccione el certificado de distribución correcto

   Seleccione el certificado que exportó en el paso anterior y haga clic en el Continue botón

   

   Si no está seguro de qué certificado seleccionar, regrese a Keychain Access y encuentre el certificado que exportó. Luego, revise la fecha de vencimiento.

   

8. Asigne un nombre al perfil

   Dale un nombre al perfil y haga clic en el Generate botón

   Consejo

   El nombre de perfil se extrae automáticamente por Capgo CLI — no necesita recordarlo.

   

9. Descargar el perfil

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

   Cuidado

   Este archivo DEBE SER GUARDADO - necesitarás para más adelante

   

Felicidades 🎉 Ahora tienes todo lo que necesitas para configurar Capgo Native Build.

Advertencia

Neveras debes comprometer las credenciales que acabas de crear en tu repositorio. Manténlas seguras! 🔒

Ejecutar el comando de configuración

¡Lo has hecho! Ahora tienes todo lo que necesitas para configurar Capgo Native Build.

El comando que necesitarás 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

Sustituye los valores de reemplazo

Sustituye los valores de reemplazo anteriores con tus credenciales reales recopiladas en los pasos anteriores:

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

If everything went well, you will see the following output:

Autenticación de Apple fallida? Sincroniza tu reloj

If the App Store Connect API key looks correct but authentication still fails, sync your computer clock and retry. Capgo signs Apple’s JWT with your local system time, and Apple rejects tokens that expire more than 20 minutes in the future. A clock that is only a few seconds out of sync can be enough to fail this step.

Consulte el guía de solución de problemas del constructor para los pasos de sincronización del reloj.

Configuración de CI/CD (GitHub Acciones)

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

1) Convierta archivos de credenciales a base64 de 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

Tip

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

2) Crea secretos de repositorio

En GitHub > Repository > Settings > Secrets and variables > Actions, agregar:

Nombre secreto	Valor
CAPGO_TOKEN	Tu token Capgo API
APP_STORE_CONNECT_TEAM_ID	ID de equipo desde ID de equipo
APPLE_KEY_ID	ID de clave desde Apple key, ID de clave de Apple y ID de emisor de Apple
APPLE_ISSUER_ID	Identificador de emisor desde Apple key, ID de clave de Apple y ID de emisor de Apple
BUILD_CERTIFICATE_BASE64	Contenido de certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Generado por CLI — copiar desde .capgo-credentials archivo
APPLE_KEY_CONTENT	Contenido de apple_key_base64.txt
P12_PASSWORD (opcional)	Su .p12 contraseña si se estableció durante la exportación

3) Utilice variables de entorno en su GitHub Actions workflow

.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, CI envía credenciales a través de variables de entorno solo. No necesita comprometer archivos de firma ni subirlos como artefactos de flujo de trabajo.

Corriendo la compilación

Ahora, está listo para ejecutar su primera compilación.

Ejecute el siguiente comando para compilar su aplicación:

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

Felicidades 🎉 En este punto, ha compilado con éxito su aplicación y está lista para ser enviada a la revisión de la Tienda de Aplicaciones.

Enviar a revisión de la Tienda de Aplicaciones

El camino de construcción normal de App Store sube la construcción a App Store Connect/TestFlight. Si su lanzamiento de CI también debe adjuntar la construcción procesada de TestFlight a la versión de App Store y enviarla para revisión de App Store, pase --submit-to-store-review Con una construcción de lanzamiento:

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 credenciales de clave de App Store Connect API (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, y APP_STORE_CONNECT_TEAM_IDCarga de contraseñas de aplicación y ad_hoc es la versión de App Store; si se omite, __CAPGO_KEEP_0__ lee --store-release-name es la versión de la Tienda de Aplicaciones; si se omite, Capgo lee MARKETING_VERSION desde el proyecto de Xcode. --store-release-notes Es el texto de "Nuevos contenidos" de la App Store por defecto, y cada --store-release-notes-locale "locale=notes" La entrada puede sobrescribirlo para una localización de tienda. Utilice --ios-automatic-release para liberar automáticamente después de la aprobación de Apple, o --no-ios-automatic-release para esperar a una liberación manual. --ios-testflight-groups Aún está disponible para distribución de beta externa, pero no es necesario para la presentación de la aplicación en la Tienda de App.

Modo de distribución Ad-Hoc

Por defecto, Capgo compila aplicaciones iOS para la distribución de la Tienda de App (TestFlight + Tienda de App). Si necesita compilaciones ad-hoc en su lugar (para pruebas internas o recopilación de artefactos de CI), puede utilizar la --ios-distribution bandera.

Nota

La distribución ad-hoc no es igual que la distribución Enterprise (en casa). La distribución Enterprise requiere una cuenta de desarrollador Apple Enterprise separada y utiliza perfiles de configuración diferentes. Capgo admite actualmente 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 construcción mediante --output-upload sin presentar a la tienda de aplicaciones

Requisitos

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

credencial	¿Requerida?
certificado de distribución (.p12)	Sí
Perfil de provisión ad-hoc (".mobileprovision)	Sí
ID de equipo ("--apple-team-id)	Sí
App Store Connect API clave (.p8)	No
Apple Key ID / Identificador de Emisor	No

Nota

En ad_hoc modo, --apple-key, --apple-key-idy --apple-issuer-id no están soportados y se ignoran. Esto es por qué las dos filas de App Store Connect arriba no muestran banderas de CLI ad-hoc; estas opciones solo se aplican app_store modo solo.

Cuidado

Sin una clave API de App Store Connect, el número de compilación utiliza un fallback basado en fecha y hora. Para suprimir la advertencia, pase --skip-build-number-bump.

Creando un perfil de provisión ad-hoc

Sigue los mismos pasos que Perfil de provisiónProfil de provisión Ad Hoc Ad Hoc en lugar de:

1. Vaya a Perfiles de Desarrollador de Apple
2. Haga clic en + Haz clic en el
3. Seleccionar Ad Hoc y haz clic en Continuar
4. Selecciona tu aplicación y certificado de distribución
5. Selecciona los dispositivos que deseas registrar
6. Nombra y descarga el perfil

Almacenando credenciales de 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 recopilar el IPA como un artefacto de build, agrega --output-upload:

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

CI/CD con builds ad-hoc

Para GitHub Acciones, necesitas menos secretos que builds de App Store:

github/trabajos/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

Observa que APPLE_KEY_ID, APPLE_ISSUER_ID, y APPLE_KEY_CONTENT no son necesarios para compilaciones ad-hoc.

Aplicaciones con Extensiones (Firma de múltiples objetivos)

Si tu aplicación incluye extensiones (extensiones de compartir, widgets, extensiones de servicios de notificaciones, etc.), cada objetivo de extensión necesita su propio perfil de provisión. Capgo admite esto mediante la bandera repetible. --ios-provisioning-profile flag.

Sección titulada “Ejemplo: Aplicación + Extensión de Compartir”

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 La bandera mapea un ID de paquete a su archivo de perfil de provisión. El CLI:

1. Lee cada archivo mobileprovision
2. Extrae automáticamente el nombre del perfil desde el plist incorporado
3. Codifica en Base64 el archivo
4. Almacena todo como un solo CAPGO_IOS_PROVISIONING_MAP credencial

Consejo

Necesita un certificado de distribución para todos los objetivos — solo los perfiles de configuración difieren por objetivo.

Migración desde Perfil Único

Si anteriormente utilizaste BUILD_PROVISION_PROFILE_BASE64 (ejecuta un perfil único), ejecuta:

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

Esta convierte tus credenciales de perfil único existentes al nuevo CAPGO_IOS_PROVISIONING_MAP formato y elimina las claves legadas (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Después de la migración, agrega perfiles de extensión con el update comando (unión aditiva):

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

Consejo

Utiliza update (no save) para agregar perfiles a credenciales existentes. El update comando combina nuevos perfiles con los existentes. Utiliza save solamente al configurar todas las credenciales desde cero.

Troubleshooting

Sección titulada “Resolución de problemas”

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 ha habilitado una nueva capacidad después de crear el perfil de provisión. El antiguo perfil de provisión no incluye la nueva capacidad todavía.

Para solucionar esto, necesita regenerar el perfil de provisión.

1. Abrir Portal del desarrollador de Apple
2. Seleccione la cuenta correcta en el menú desplegable
3. Haga clic en el Profiles botón
4. Encuentre el perfil de provisión que desee regenerar
5. Haga clic en el Edit botón
6. Haga clic en el Save botón
7. Haga clic en el Download botón
8. Re-run the Capgo Native Build setup command con el perfil descargado recientemente.

Esto debería solucionar el problema.

Otros problemas

Si por alguna razón estás teniendo problemas con Capgo Native Build, la configuración de las credenciales o la compilación de la aplicación, no dudes en contactarnos a través de nuestro soporte.

Sigue adelante desde iOS Builds

Si estás utilizando iOS Builds para planificar la automatización de CI/CD, conecta con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD, Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Builds nativos Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones Integración CI/CD para el detalle de implementación en Integración CI/CD, y GitHub Integración de Acciones para el detalle de implementación en GitHub Integración de Acciones