Saltar al contenido principal
Tutorial

Compila una app de iOS desde Linux con Capacitor y Capgo Build

Publica un build de iOS firmado en TestFlight desde Ubuntu, Fedora o cualquier máquina Linux: genera el proyecto ios/ con Capacitor, crea los certificados con OpenSSL y deja que Capgo Build lo compile y lo envíe sin necesidad de un Mac.

Crea una app de iOS desde Linux con Capacitor y Capgo Ilustración del blog sobre Capgo

Linux es un entorno cómodo para escribir apps de Capacitor, y Android se distribuye desde él sin compromisos. iOS es la excepción: Xcode y las herramientas de firma de Apple solo funcionan en macOS. La solución no es un Mac mini bajo el escritorio. Es generar el proyecto de iOS localmente y compilarlo en macOS en la nube.

Esta guía es la versión para Linux de Crea una app iOS desde Windows con Capacitor y Capgo Build. Cubre las partes que difieren en Linux: certificados de OpenSSL, una shell de Linux y CI desde runners de Linux.

La división del trabajo

Una app Capacitor tiene dos builds:

  • Build web: el output de tu framework en dist/. Hecho en Linux.
  • Native Build: archive de Xcode, firma y subida. Hecho por Build de Capgo en máquinas con Apple Silicon que ejecuten la versión actual de macOS y Xcode.

El CLI sube el preparado ios/ proyecto desde tu máquina. No hace falta subir nada a un host de Git, y ninguna credencial de registro privado sale de tu equipo, ya que las instalaciones de dependencias y cap sync ocurre localmente antes de la subida.

Requisitos

  • Una app de Capacitor que se compila localmente (cualquier framework).
  • Node 20+ o Bun en Linux.
  • Una membresía del Apple Developer Program.
  • OpenSSL (instalado por defecto en casi todas las distribuciones).
  • Una cuenta de Capgo y la app registrada con bunx @capgo/cli@latest app add.

1) Generar el proyecto iOS en Linux

bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add ios

You will see something like Skipping pod install because CocoaPods is not installed. Es lo esperado. La ios/ carpeta existe y debe ser commiteada; contiene tu bundle ID, Info.plist, iconos y configuración nativa.

2) Sincronizar los assets web antes de cada build

bun run build
bunx cap sync ios

cap sync copia dist/ en ios/App/App/public y actualiza las referencias de plugins. Capgo compila lo que hay en ios/, por lo que un proyecto sin sincronizar envía tu interfaz anterior.

3) Crear el material de firma sin un Mac

Necesitas tres cosas: un certificado de Apple Distribution como .p12, un perfil de aprovisionamiento de App Store y una clave API de App Store Connect. Ninguno requiere Keychain Access.

Certificado de distribución con OpenSSL

openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Your Name/C=US"

Subir ios_distribution.csr en Certificates, Identifiers & Profiles, elige Apple Distribution y descarga distribution.cer. Convierte y empaqueta:

openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
  -out ios_distribution.p12 -legacy

El -legacy El flag es importante con OpenSSL 3. Sin él, las herramientas de Apple rechazan .p12 con un error de contraseña inválida, incluso cuando la contraseña es correcta. Si prefieres no tocar OpenSSL, el generador de certificados iOS hace lo mismo en el navegador.

Perfil de aprovisionamiento y la clave API

En el portal de Apple Developer, crea un perfil de App Store para tu bundle ID que use el nuevo certificado y descarga el .mobileprovision. En App Store Connect, crea una clave API con el rol de App Manager y descarga el .p8; anota el Key ID y el Issuer ID. El guía de build de iOS muestra cada pantalla.

¿Quieres inspeccionar un perfil en Linux? openssl smime -inform der -verify -noverify -in profile.mobileprovision imprime el plist incrustado.

4) Guardar las credenciales en Capgo

bunx @capgo/cli@latest login
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id "TEAMID" \
  --apple-key ./AuthKey_KEYID.p8 \
  --apple-key-id "KEYID" \
  --apple-issuer-id "issuer-uuid" \
  --certificate ./ios_distribution.p12 \
  --ios-provisioning-profile ./App_Store.mobileprovision

O ejecuta bunx @capgo/cli@latest build init --platform ios para la versión guiada. En Linux, el paso de la clave de App Store Connect es manual; todo lo demás se pide con prompts.

Si Apple rechaza la clave con un error de autenticación, sincroniza tu reloj. El JWT se firma con la hora local y Apple rechaza los tokens que se desfasan demasiado:

timedatectl status
sudo timedatectl set-ntp true

5) Solicitar el build

bun run build
bunx cap sync ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

El preparado ios/ proyecto preparado se sube, Capgo se ejecuta pod install, archiva con Xcode, firma con tu certificado y transmite los logs a tu terminal. Con la clave API configurada, el build se envía a TestFlight al terminar. Instala la app TestFlight en un iPhone para ejecutarlo.

Los builds que fallan pueden diagnosticarse automáticamente añadiendo --ai-analytics; el diagnóstico de build con IA lee el log de Xcode y explica la solución.

6) Builds ad hoc para testers sin TestFlight

Para un dispositivo de QA registrado por UDID, usa un perfil Ad Hoc y guarda el IPA como artefacto:

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

El CLI imprime un enlace de descarga temporal. Añade --output-record build.json para guardar el enlace y un QR code para un tester.

7) Automatiza desde un runner de CI Linux

Los mismos comandos se ejecutan en cualquier CI Linux. Ejemplo con GitHub Actions:

name: iOS build
on:
  workflow_dispatch:
jobs:
  ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun run build
      - run: bunx cap sync ios
      - run: bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Las credenciales del paso 4 se guardan en Capgo, así que el runner solo necesita el token. Como alternativa, exporta un CI .env con bunx @capgo/cli@latest build credentials manage y pasa los valores como secrets; consulta la gestión de credenciales.

8) Iteración diaria sin builds nativos

Una vez que el build de TestFlight existe, la mayoría de los cambios son web. Súbelos con Live Updates de Capgo:

bun run build
bunx @capgo/cli@latest bundle upload --channel production

Reserva build request para añadir plugins, cambios de permisos, de iconos y actualizaciones de Capacitor.

Problemas en Linux

  • Olvidaste cap sync ios: el IPA muestra la UI antigua. Haz sync antes de cada petición.
  • ios/ en .gitignore: CLI sube desde el disco, así que compila igual, pero tus compañeros y la CI no tendrán el proyecto nativo. Haz commit.
  • .p12 contraseña rechazada: regenera con -legacy.
  • Error de autenticación de Apple: desincronización del reloj. Activa NTP.
  • Plugin añadido, olvidaste el rebuild nativo: añadir un plugin de Capacitor modifica el binario nativo. Ejecuta un nuevo cloud build y un envío a la tienda antes de publicar cambios web que lo llamen.

Resumen

Linux no puede ejecutar Xcode, pero no lo necesita. Genera ios/ con Capacitor, genera certificados con OpenSSL y deja que Capgo Build compile, firme y envíe a TestFlight. Con Live Updates para la capa web, un equipo que solo usa Linux publica iOS con la misma normalidad que Android. Para la configuración completa del entorno, lee Desarrollo de Capacitor en Linux.

Live updates para apps Capacitor

Cuando un bug de la capa web está en producción, publica el fix a través de Capgo en lugar de esperar días a la aprobación de la app store. Los usuarios reciben la actualización en segundo plano mientras los cambios nativos siguen el flujo de revisión habitual.

Lo último de nuestro blog

Capgo te da la información clave que necesitas para crear una app móvil realmente profesional.