Compilaciones 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á a subir su aplicación mediante Capgo Native build
• Aprenderá a configurar los certificados para Capgo Native Build

Requisitos previos

• Una cuenta de Capgo (basta con una prueba gratuita para empezar)
• Su aplicación ya registrada en Capgo (ejecute 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 válida de Apple ($99/año) (Debes tener derechos de administrador o propietario en la cuenta de desarrollador de Apple)
• Su aplicación debe poder compilar con éxito mediante Xcode
• Una aplicación de Capacitor
• Un icono configurado para la aplicación. Las aplicaciones sin icono no pueden subirse a la Tienda de App

Nota

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

Antes de empezar en los portales de Apple

Antes de configurar certificados o desencadenar tu primer envío de TestFlight, asegúrate 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
• Elegir el tipo de membresía correcto:
  • Persona física / Propietario individual: su nombre legal 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 tanto a Apple Developer como a App Store Connect para certificados, registros de aplicaciones, API claves y TestFlight
• Bloquee su ID de paquete final temprano. Cambiarlo más tarde suele significar volver a configurar App Store
• Planifique estos elementos de App Store Connect antes de la revisión de App: URL de soporte, URL de política de privacidad, clasificación de edad, capturas de pantalla, cumplimiento de exportación y detalles de contacto de revisión de 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 plataforma en App Store Connect

Cuidado

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 compiladas con el iOS & iPadOS 26 SDK o posterior.

Recomendado: onboarding automatizado

No tiene que hacer nada de esto a mano. El onboarding de 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 paso a paso a continuación solo es para aquellos que prefieren configurar las credenciales ellos mismos, o quieren entender exactamente qué Capgo hace debajo de la cubierta.

La primera compilación manual

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

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

Antes de que podamos 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. Hacer clic en Xcode -> Settings... Alternativamente, puedes utilizar el atajo Cmd + ,

   

3. Ir 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. Haz clic en el Manage Certificates... botón

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

8. Si no lo haces, necesitarás crear un nuevo certificado.

   Nota

   Apple limita el número de certificados de distribución que puedes tener a 3. Si tienes más de 3 certificados, necesitarás eliminar uno para poder crear uno nuevo. No cubriré eso en este 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. Mira el paso anterior para confirmar que lo ves.

Ahora que tienes el certificado de distribución instalado, puedes 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. Esperar a que se complete la compilación

4. Haga clic en el Distribute App botón de distribución de Xcode

   

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

   

6. Configure el registro de la aplicación

   Rellene los siguientes campos:

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

   Luego, haga clic en el next botón

   

7. Si falla la creación del registro de la aplicación, intente cerrar la ventana y trate de archivar la aplicación nuevamente.

8. Espera a que se complete la subida

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

10. Haga clic en el botón Done Puede pensar que todo está bien ahora y que podrá ver su aplicación en TestFlight ahora, pero hay un par de cosas más que terminar:

Agregue su nombre a TestFlight

1. Complete la conformidad de exportación para que la construcción se vuelva testable
2. Rellene los metadatos de App Store Connect obligatorios, como su URL de soporte, URL de política de privacidad y clasificación de edad
3. Prepare capturas de pantalla que coincidan con los dispositivos que realmente soporta
4. Agregue los detalles de contacto de revisión de la aplicación y cualquier credencial de prueba antes de la presentación de producción
5. Haga clic en el "button"

Comencemos con el primero:

Agregarse a TestFlight

1. Ir a la página de App Store Connect página de inicio de sesión de App Store Connect

2. Seleccionar el equipo que utilizó cuando creó el registro de la aplicación. Si solo tiene una cuenta de desarrollador, puede saltarse este paso.

3. Selección del equipo de App Store Connect

4. botón Apps Selección del equipo de App Store Connect

5. Encuentre la aplicación que creó en el paso anterior y haga 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”. Puede llamarlo como quiera.

   

9. Haz clic en Invite testers botón

10. Agrega tu nombre a la lista

    Encuentra tu nombre en la lista y selecciona la casilla al lado de tu nombre. (Puede que debas refrescar la página para ver tu nombre) Luego, haz clic en el Add botón de casilla de verificación de pruebas de App Store Connect

    

11. Ahora deberías ver tu nombre en la lista

    App Store Connect verificar pruebas

    

Congratulations 🎉 You have added yourself to TestFlight. Now, there is just one more thing you need to do before you can configure 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 sugiero leer el documentación de Apple sobre cómo manejar esto.

1. Existen dos formas de hacer esto:
2. Puedes hacer esto a mano cada vez que construyas tu aplicación. false.

Puedes configurar tu archivo plist para establecer automáticamente este valor en

1. Vamos a empezar con la primera opción:

2. Sigue todos los pasos de la sección anterior para encontrar la sección TestFlight en App Store Connect Builds -> iOS

3. botón de construcción de iOS de App Store Connect Manage

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

   Para mí, esto es nonePero podría ser diferente para ti. Después, haga clic en guardar

   

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

   

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

1. Abra el Info.plist archivo

2. Agregar la siguiente clave:

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

3. Guardar el archivo

Nota

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

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

Ahora, estás 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 Mac App Store en tu dispositivo iOS/iPadOS
2. Aceptar la invitación para probar tu aplicación

No entraré en detalles sobre 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. Abre el correo electrónico 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 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 Compilación Nativa para compilar y enviar tu aplicación a TestFlight.

Configurando Capgo Compilación Nativa

Hay un par de cosas que debes configurar en Capgo Compilación Nativa para poder compilar y enviar tu aplicación a TestFlight. Aquí tienes una lista de las cosas que pasarás a la Capgo CLI:

Parámetro	Descripción
--platform	La plataforma para la que deseas compilar (ios)
--apple-team-id	Su ID de equipo de desarrollador de Apple (encontrado en Portal de desarrollador de Apple)
--apple-key	Ruta a su archivo de clave de App Store Connect API (.p8 archivo)
--apple-key-id	La clave ID de su clave de App Store Connect API
--apple-issuer-id	Su ID de emisor de App Store Connect
--certificate	Ruta a su certificado de distribución (.p12 archivo)
--ios-provisioning-profile	Mapeo de perfil de configuración (bundleId=path o solo 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

Comencemos con el ID de equipo. Encontrarlo es bastante fácil.

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

2. Encuentra la 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 — créame 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. Ir a página de acceso de usuario y acceso de App Store Connect

   Nota

   Para mí, el enlace a veces 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 utilizar

3. Haz clic en el Integrations botón

4. Encuentra el issuer

   Cuidado

   Esto 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 de

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

7. Guardar el ID de la clave

   Cuidado

   Esto __CAPGO_KEEP_0__ - lo necesitarás más tarde

   

8. Descargar la clave

   Cuidado

   Esto __CAPGO_KEEP_0__ - 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 llave

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

2. Seleccione la login __CAPGO_KEEP_0__ My Certificates categoría y haga clic en el

3. Categoría de inicio de sesión de Keychain Access

   Encuentre su certificado en la lista Apple Distribution: [Your Name/Company] (your team ID)

4. Buscar certificado de Keychain Access Export

5. Guarde el certificado como un .p12 archivo

   Advertencia

   Este __CAPGO_KEEP_0__ - lo necesitarás más tarde

   1. Asegúrate de seleccionar un buen nombre para el archivo de certificado
   2. Asegúrate 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 solicite la contraseña, puede elegir entre:

   • Saltarse 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 establecerla aquí. Los archivos protegidos por 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 Diálogo de contraseña de certificado de acceso a la llave

   

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

   botón. Allow Acceso a la llave de certificado de inicio de sesión

   

When asked for the password, you can either: Skip the password (recommended for simplicity): Click without entering a password Set a password: If you prefer to protect your certificate with a password, you can set one here. Password-protected files are fully supported by the __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - just provide the password using the option when running configuration command.

Perfil de configuración

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

1. Ir a Perfiles del desarrollador de Apple

2. Seleccionar el equipo correcto en el menú desplegable

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

3. Asegúrate de estar en la página correcta Debería parecerse a esto, si no haz 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 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, mire la fecha de vencimiento.

   

8. Nombre del perfil

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

   Consejo

   El nombre del 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 - lo necesitará más tarde

   

Felicidades 🎉 Ahora tiene todo lo que necesita para configurar Capgo Native Build.

Cuidado

No cometas 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

Sustituir valores de reemplazo

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

• --apple-team-idTu ID de equipo de Apple
• --apple-keyRuta a tu archivo descargado .p8 archivo clave
• --apple-key-id: Su clave de identificación de Apple
• --apple-issuer-id: Su ID de emisor de Apple
• --certificate: Ruta a su archivo exportado .p12 certificado
• --ios-provisioning-profile: Ruta a su archivo descargado .mobileprovision : Ruta a su archivo descargado (identificador de paquete autoinferido para perfiles únicos)

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

Falló la autenticación de Apple? Sincronice su reloj

Si el archivo de clave de App Store Connect API parece correcto pero la autenticación sigue fallando, sincronice el reloj de su computadora y vuelva a intentarlo. Capgo firma el JWT de Apple con el tiempo de su 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.

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

Configuración de CI/CD (GitHub)

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

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

Consejo

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

2) Crea secretas de repositorio

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

Nombre secreto	Valor
CAPGO_TOKEN	Su Capgo API token
APP_STORE_CONNECT_TEAM_ID	ID del equipo desde ID del 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 Clave de Apple, 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 — 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 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.

Ejecutando 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 Tienda de Aplicaciones.

Enviar a revisión de la Tienda de Aplicaciones

El camino de compilación normal de la Tienda de Aplicaciones 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 la Tienda de Aplicaciones y enviarla para revisión, pase --submit-to-store-review con una compilació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

Requiere credenciales de clave de App Store Connect API (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, y APP_STORE_CONNECT_TEAM_ID). La carga de contraseñas de aplicación y la distribución no pueden enviar una compilación para revisión. ad_hoc es la versión de App Store; si se omite, __CAPGO_KEEP_0__ lee --store-release-name is the App Store version; if omitted, Capgo reads MARKETING_VERSION es el texto de '¿Qué hay de nuevo' de App Store de respaldo, y cada --store-release-notes entrada puede sobrescribirlo para una localización de tienda. Utilice --store-release-notes-locale "locale=notes" para liberar automáticamente después de la aprobación de Apple, o --ios-automatic-release para esperar a una liberación manual. --no-ios-automatic-release aún está disponible para la distribución de beta externa, pero no es necesario para la presentación de la compilación para la revisión de App Store. --ios-testflight-groups Modo de distribución Ad-Hoc

Modo de distribución Ad-Hoc

Por defecto, Capgo compila aplicaciones iOS para distribución en la Tienda de Aplicaciones (TestFlight + Tienda de Aplicaciones). Si necesita builds 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 lo mismo que la distribución de empresa (In-House). La distribución de empresa requiere una cuenta de desarrollador de Apple Enterprise separada y utiliza perfiles de configuración diferentes. __CAPGO_KEEP_0__ admite actualmente y 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 Cuándo usar el modo ad-hoc ad_hoc Sección titulada “Cuándo usar el modo ad-hoc”

Section titled “Modo de Distribución Ad-Hoc”

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

Requisitos

Los builds Ad-hoc tienen menos requisitos que los builds de la tienda 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í
Clave de App Store Connect API (.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 e ignorados. Esto es por qué las dos filas de App Store Connect arriba no muestran banderas de CLI ad-hoc; estas opciones se aplican solo al app_store modo solo.

Cuidado

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

Creación de un perfil de provisión ad-hoc

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

1. Ir a Perfiles de desarrollador de Apple
2. Haz clic en el + botón
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. Nombre y descargar el perfil

Guardar 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 recopilar el IPA como un artefacto de compilación, agregue --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, necesita menos secretos que las 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

Consejo

Tenga en cuenta que APPLE_KEY_ID, APPLE_ISSUER_ID, y APPLE_KEY_CONTENT no se necesitan para compilaciones ad-hoc.

Aplicaciones con Extensiones (Firma de múltiples objetivos)

Si su aplicación incluye extensiones (extensiones de compartición, widgets, extensiones de servicios de notificaciones, etc.), cada objetivo de la extensión necesita su propio perfil de provisión. Capgo admite esto mediante la bandera --ios-provisioning-profile Ejemplo: Aplicación + Extensión de Compartición

Ventana de Terminal

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"

Lee cada archivo mobileprovision --ios-provisioning-profile flag maps a bundle ID to its provisioning profile file. The CLI:

1. bandera mapea un ID de paquete a su archivo de perfil de provisión. El __CAPGO_KEEP_0__: lee cada archivo mobileprovision
2. Extrae automáticamente el nombre de perfil desde el plist incorporado
3. Codifica Base64 el archivo
4. Almacena todo como un CAPGO_IOS_PROVISIONING_MAP credencial

Consejo

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

Migración desde Perfil Único

Si anteriormente utilizó BUILD_PROVISION_PROFILE_BASE64 (perfil único), ejecute:

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

Esta convierte sus credenciales de perfil único existentes al nuevo formato y elimina las llaves legadas ( CAPGO_IOS_PROVISIONING_MAP Después de la migración, agrega perfiles de extensión con el comando (unión aditiva):BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Ventana de terminal update Copiar a portapapeles

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

(no

) para agregar perfiles a credenciales existentes. El update El saveEl update El comando combina nuevos perfiles con los existentes. Utilice save solo cuando esté configurando todos los credenciales desde cero.

Solució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')"

Esto sucede 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 equipo correcto 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-ejecutar el comando de configuración de Capgo Native Build con el perfil descargado recientemente. Esto debería solucionar el problema.

Otros problemas

Sección titulada “Otros problemas”

If for whatever reason you are having issues either with Capgo Native Build, configuring the credentials or building the app, please don’t hesitate to reach via our Siga adelante desde iOS Builds.

soporte

Si estás utilizando Builds de iOS 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 Builds nativos 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 de CI/CD para el detalle de implementación en Integración de CI/CD, Acciones de GitHub Integración para el detalle de implementación en Acciones de GitHub Integración.