Genera Builds de iOS

Construye y envía 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 (ejecuta bunx @capgo/cli@latest app add si no)
• Un ordenador Mac con Xcode instalado (es posible configurar la compilación en una máquina Linux/Windows, pero aún no está documentado)
• Una cuenta de desarrollador Apple válida (99€/año) (Debes tener derechos de administrador o propietario en la cuenta del desarrollador Apple)
• Su aplicación debe poder compilar con éxito mediante Xcode
• Una aplicación Capacitor
• Un icono configurado para la aplicación. Las aplicaciones sin icono no pueden subirse a la Tienda de Mac App Store.

Nota

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

Antes de empezar en los portales de Apple

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

• Activar la autenticación en dos factores para la cuenta de Apple utilizada para la inscripción
• Elige el tipo de membresía correcto:
  • Persona / Propietario Individual: se convierte en el nombre del vendedor en la Tienda de Mac
  • Organización: requiere una entidad legal, un número D-U-N-S, un sitio web de la 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 ambos Apple Developer y App Store Connect para certificados, registros de aplicaciones, API claves y TestFlight
• Concentre su ID de paquete final temprano. Cambiarlo más tarde suele significar volver a configurar la tienda de App Store
• Planee estos elementos de App Store Connect antes de la revisión de la App: URL de soporte, URL de política de privacidad, calificación de edad, capturas de pantalla, cumplimiento de exportación y detalles de contacto de revisión de la App

Nota

Referencias oficiales útiles:

• Convertirse en miembro del programa de desarrolladores de Apple
• Enviar 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 2026Los aplicativos de iPhone e iPad subidos a App Store Connect deben ser compilados con el iOS y iPadOS 26 SDK o posterior.

Recomendado: onboarding automatizado

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

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

La guía 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á la certificación de distribución en su máquina local
• Crearán el registro de la Tienda de Mac si no lo han hecho aún
• Podrá descubrir cualquier problema con el proceso de construcción relacionado con su aplicación code

Antes de que podamos comenzar, debe tener la certificación de distribución instalada en su máquina local. Esto es bastante complejo, pero lo explicaré a continuación.

Configurando el certificado de distribución

1. Abre Xcode

2. Haz clic en Xcode -> Settings... Alternativamente, puedes utilizar la atajada Cmd + ,

   

3. Ve a Accounts

4. Encuentra la cuenta de Apple que se ha agregado a la cuenta del desarrollador de Apple

5. Encuentra el equipo que utilizarás 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 hace, 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é eso en el tutorial.

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

Ahora que tiene instalado el certificado de distribución, puede comenzar el proceso de compilación.

Compilación manual para TestFlight

1. Abrir la aplicación en Xcode

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

2. Encuentre y haga clic en el archive botón

   En la barra de herramientas de Xcode, encuentre y haga clic en el product -> archive botón.

   

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
   3. El idioma principal - el idioma principal de tu aplicación

   Luego, haz clic en el next botón

   

7. Si falla la creación de la aplicación de registro, 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

Puede que te parezca instintivamente 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 tienes que terminar:

1. Añade a ti mismo a TestFlight
2. Complete la conformidad exportadora para que la compilación se vuelva susceptible de pruebas
3. Rellene los metadatos de App Store Connect obligatorios, como su URL de soporte, política de privacidad y clasificación de edad
4. Prepare capturas de pantalla que coincidan con los dispositivos que realmente soporta
5. Agregue los detalles de contacto de revisión de la App y cualquier credencial de prueba antes de la presentación de producción

Empecemos con el primero:

Agregarse a TestFlight

1. Vaya a la Página de App Store Connect Página de inicio de sesión de App Store Connect

2. Inicie sesión con su cuenta de desarrollador de Apple

3. Seleccione 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. Encuentre la aplicación que creaste en el paso anterior y hágale clic

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 quieras.

   

9. Haga clic en Invite testers botón

10. Agregar a sí mismo al grupo

    Encuentre a sí mismo 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. Verifique que se ha agregado a sí mismo 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.

Configuración de la información de conformidad.

Ahora necesitas prometer a Apple que tu aplicación no utiliza ningún cifrado no estándar (como un algoritmo personalizado). Si tu aplicación utiliza algún cifrado no estándar, te recomiendo leer el documentación de Apple sobre 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 a false.

Vamos a empezar con la primera opción:

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

2. Haz clic en Builds -> iOS

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

4. Selecciona la opción que mejor describe tu aplicación

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

   

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

   

En cuanto a la segunda, aquí están los pasos:

1. Abre el Info.plist idioma objetivo

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 es CASI listo para probar tu aplicación en TestFlight. Antes, necesitas hacer las siguientes cosas:

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

Saltaré los detalles de cómo instalar la aplicación TestFlight en tu dispositivo. Si no estás 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ás 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. Hacer clic en el Install botón

4. Instala la aplicación en tu dispositivo

   Si has instalado la aplicación anteriormente 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

There are a few things you need to configure in Capgo Native Build to be able to build and submit your app to TestFlight. Here is a list of the things you will pass to the Capgo CLI:

Aquí tienes una lista de las cosas que pasarás al __CAPGO_KEEP_1__ __CAPGO_KEEP_2__:	Parámetro
--platform	Descripciónios)
--apple-team-id	La plataforma para la que deseas compilar ( Tu ID de equipo de desarrollador de Apple (encontrado en)
--apple-key	Path to your App Store Connect API Key file (.p8 Ruta a tu archivo de clave __CAPGO_KEEP_0__ de App Store Connect (
--apple-key-id	The Key ID of your App Store Connect API Key
--apple-issuer-id	La clave ID de tu clave __CAPGO_KEEP_0__ de App Store Connect
--certificate	Tu ID emisor de App Store Connect.p12 Ruta a tu certificado de distribución (
--ios-provisioning-profile	Mapeo de perfil de configuración (bundleId=path o simplemente ruta para un perfil único)

Ejemplo de comando:

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

Ir a

1. Cuenta de desarrollador de Apple y desplazarse hacia abajo Encuentre el

2. Find the Team ID

   

Clave de Apple, ID de clave de Apple y ID de emisor de Apple

Ahora, pasemos a la clave de Apple.

macOS: ¡deja que Capgo cree esta clave para ti!

En macOS, capgo build init puedes crear esta clave de App Store Connect API para ti. Elige “No — crea una para mí” y una ventana guiada se abre en App Store Connect, te 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 del usuario y acceso de App Store Connect

   Nota

   A veces el enlace no funciona. Recarga la página si no funciona para ti.

2. Selecciona el equipo correcto en el menú desplegable

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

3. Haz clic en el Integrations botón

4. Encuentra el issuer

   Cuidado

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

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

5. Haz clic en el botón de signo más

6. Establece el nombre de la clave y establece el acceso a App manager y haz clic en el Generate botón

7. Guardar el ID de clave

   Cuidado

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

   

8. Descargar la clave

   Cuidado

   Esto ES 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 llave de Apple, el ID de la llave de Apple y el ID del 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 sabiduría infinita, decidió que la forma en que exportas el certificado es bastante diferente de la forma en que los creas 🙃 Vamos a entrar en la configuración:

1. Abrir Keychain Access

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

2. Seleccione la login categoría y haga 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

   Cuidado

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

   1. Asegúrate de seleccionar un buen nombre para el archivo de certificado
   2. Asegúrese de que el formato del archivo esté configurado en 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 prefiere proteger su certificado con una contraseña, puede establecer una aquí. Los archivos protegidos con contraseña están completamente soportados por el __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - basta con proporcionar la contraseña utilizando la .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password Cuando se le pregunte por la contraseña de la 'llave de inicio de sesión', proporcione la contraseña que utiliza para iniciar sesión en su Mac

   

7. Cuando se le pregunte por la contraseña de la 'llave de inicio de sesión', proporcione la contraseña que utiliza para iniciar sesión en su Mac

   Introduzca 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 provisión

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

1. Vaya a Perfiles de desarrollador de Apple

2. Seleccione el equipo correcto en el menú desplegable

   1. Haga clic en su nombre en la esquina superior derecha
   2. Haga clic en el equipo que desea utilizar

3. Asegúrese de estar en la página correcta Debería parecerse a esto, si no haga clic en profiles en el menú lateral

   

4. Haga clic en el + botón

5. Seleccione el tipo de perfil Seleccione App Store Connect y haga 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 __CAPGO_KEEP_0__

   

7. Seleccione el certificado de distribución correcto

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

   

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

   

8. Asigne un nombre al perfil

   Dale un nombre al perfil y haga clic en el Generate __CAPGO_KEEP_0__

   Tip

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

   

9. Descargar el perfil

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

   Cuidado

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

   

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

Cuidado

Nunca comites las credenciales que acabas de crear en tu repositorio. Manténlas seguras! 🔒

Ejecutar el comando de configuración

Lo has logrado! 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 los reemplazos

Sustituye los valores de los reemplazos 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 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 exportado
• --ios-provisioning-profile: Ruta a tu archivo descargado .mobileprovision (ID de bundle automático inferido para perfiles únicos)

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

Apple auth falló? Sincroniza tu reloj

Si la clave de App Store Connect API parece correcta pero la autenticación sigue fallando, sincroniza el reloj de tu computadora y vuelve a intentarlo. Capgo firma Apple’s JWT con el tiempo de sistema local, y Apple rechaza tokens que expiran más de 20 minutos en el futuro. Un reloj que solo está unos segundos desfasado puede ser suficiente para fallar este paso.

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

Configuración de CI/CD (GitHub Actions)

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

1) Convierte 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

Consejo

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

2) Crea secretos de repositorio

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

Nombre de secreto	Valor
CAPGO_TOKEN	Tu Capgo API token
APP_STORE_CONNECT_TEAM_ID	ID de equipo desde ID de equipo
APPLE_KEY_ID	ID de clave desde Clave de Apple, ID de clave de Apple y ID de emisor de Apple
APPLE_ISSUER_ID	ID de emisor desde Apple key, Apple key ID y Apple issuer ID
BUILD_CERTIFICATE_BASE64	Contenido de certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Generado por CLI — copia 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 flujo de trabajo de 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 }}

Tip

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 construido con éxito su aplicación y está lista para ser sometida a revisión en la Tienda de Aplicaciones.

Someter a revisión de la Tienda de Aplicaciones

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

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_ID). Subir contraseña de App específica y ad_hoc la distribución no puede presentar una compilación para revisión. --store-release-name es la versión de App Store; si se omite, Capgo lee MARKETING_VERSION desde el proyecto de Xcode. --store-release-notes es el texto de '¿Qué hay de nuevo?' de App Store de respaldo, y cada --store-release-notes-locale "locale=notes" 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 la distribución de beta externa, pero no es necesario para la presentación de la solicitud de revisión de la Tienda de App.

Modo de Distribución Ad-Hoc

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

Nota

La distribución ad-hoc no es la misma que la distribución de la empresa (In-House). La distribución de la empresa requiere una cuenta separada de desarrollador de Apple y utiliza perfiles de configuración diferentes. __CAPGO_KEEP_0__ admite actualmente the same as Enterprise (In-House) distribution. Enterprise distribution requires a separate Apple Developer Enterprise account and uses different provisioning profiles. Capgo currently supports app_store y solo en modos. ad_hoc ¿Cuándo usar el modo ad-hoc

Sección titulada “¿Cuándo usar el modo ad-hoc”

• No tienes o no quieres usar una clave App Store Connect __CAPGO_KEEP_0__
• You don’t have or don’t want to use an App Store Connect API key
• sin someter a la tienda App Store --output-upload Requisitos

Sección titulada “Requisitos”

pocos requisitos fewer requirements que App Store builds:

Credencial	Requerido?
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
ID de clave de Apple / ID emisor	No

Nota

En ad_hoc modo, --apple-key, --apple-key-id, y --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 a app_store modo.

Precaución

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

Creando un perfil de provisión ad-hoc

Sigue los mismos pasos que Perfil de provisión, pero en el paso 5, selecciona Ad Hoc en lugar de Tienda de aplicaciones:

1. Ve a Perfiles de desarrollador de Apple
2. Haz clic en el + botón
3. Selecciona 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

Guardando 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-ido --apple-issuer-id necesario.

Realizar una compilación ad-hoc

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

Para recopilar el IPA como un artefacto de compilación, agrega --output-upload:

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

CI/CD con compilaciones ad-hoc

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

github/flujos-de-trabajo/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

Nota

Tenga en cuenta que APPLE_KEY_ID, APPLE_ISSUER_IDy APPLE_KEY_CONTENT no son necesarios para compilaciones ad-hoc.

Aplicaciones con Extensiones (Firma de múltiples objetivos)

Si su aplicación incluye extensiones (extensiones de compartir, widgets, extensiones de servicio de notificaciones, etc.), cada objetivo de la extensión necesita su propio perfil de provisión. Capgo admite esto a través de la bandera --ios-provisioning-profile flag

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 de cada identificador de paquete se mapea 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 CAPGO_IOS_PROVISIONING_MAP credencial

Consejo

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

Migración desde un perfil único

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

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

Esto convierte tus credenciales de perfil único existentes en el nuevo CAPGO_IOS_PROVISIONING_MAP formato y elimina las llaves legadas (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

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

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

Consejo

Utilice update (no save) para agregar perfiles a credenciales existentes. El update comando combina nuevos perfiles con los existentes. Utilice save solamente cuando esté configurando todas las credenciales desde cero.

Resolución de problemas

El perfil de provisión no incluye la capacidad XYZ.

A veces, puede ver el siguiente error:

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

Porque has habilitado una nueva capacidad después de crear el perfil de provisión.",

El perfil de provisión antiguo no incluye la nueva capacidad todavía.

1. Para solucionar este problema, necesitas regenerar el perfil de provisión. Abrir
2. Portal del desarrollador de Apple
3. Selección de equipo de claves del desarrollador de Apple Profiles Hacer clic en el
4. Botón de perfiles de desarrollador de Apple
5. Portal del desarrollador de Apple buscar perfil Edit botón
6. Haga clic en el Save botón
7. Haga clic en el Download botón
8. Re-ejecutar el comando de configuración de compilación nativa Capgo 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, configurando las credenciales o construyendo 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 Native Builds para el flujo de trabajo del producto en Capgo Native Builds Integraciones Capgo para el flujo de trabajo del producto en Integraciones Capgo Integración CI/CD para el detalle de implementación en Integración CI/CD Integración de Acciones GitHub para el detalle de implementación en Integración de Acciones GitHub