Compilez une app iOS depuis Linux avec Capacitor et Capgo Build

Linux est un environnement idéal pour écrire des apps Capacitor, et Android s'y déploie sans compromis. iOS est l'exception : Xcode et les outils de signature d'Apple ne fonctionnent que sur macOS. La solution n'est pas d'avoir un Mac mini sous le bureau, mais de générer le projet iOS localement et de le compiler sur macOS dans le cloud.

Ce guide est la version Linux de Compiler une app iOS depuis Windows avec Capacitor et Capgo Build. Il couvre les spécificités de Linux : les certificats OpenSSL, le shell Linux et la CI via des runners Linux.

La répartition des tâches

Une application Capacitor a deux builds :

• Build web : la sortie de votre framework dans dist/. Réalisé sur Linux.
• Build natif : l'archive Xcode, la signature et l'upload. Réalisés par Build Capgo sur des machines Apple Silicon sous les versions actuelles de macOS et Xcode.

CLI effectue l'upload du contenu préparé ios/ projet depuis votre machine. Rien n'a besoin d'être sur un hôte Git, et aucun identifiant de registre privé ne quitte votre poste, car l'installation des dépendances et cap sync tout se fait localement avant l'upload.

Prerequisites

• Une application Capacitor qui build localement (n'importe quel framework).
• Node 20+ ou Bun sur Linux.
• Un abonnement Apple Developer Program.
• OpenSSL (installé par défaut sur presque toutes les distributions).
• Un compte Capgo et l'application enregistrée avec bunx @capgo/cli@latest app add.

1) Générer le projet iOS sur Linux

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

Vous verrez quelque chose comme Skipping pod install because CocoaPods is not installed. C'est normal. Le ios/ dossier existe et doit être commit ; il contient votre bundle ID, Info.plist, icônes et paramètres natifs.

2) Synchroniser les assets web avant chaque build

bun run build
bunx cap sync ios

cap sync copie dist/ en ios/App/App/public et met à jour les références des plugins. Capgo compile le contenu de ios/, donc un projet non synchronisé déploiera votre ancienne UI.

3) Créer le matériel de signature sans Mac

Vous avez besoin de trois éléments : un certificat Apple Distribution ainsi que .p12, un profil de provisionnement App Store, et une clé API App Store Connect. Aucun ne nécessite l'accès au Trousseau.

Certificat de distribution avec 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"

Envoyer ios_distribution.csr dans Certificates, Identifiers & Profiles, choisissez Apple Distribution, et téléchargez distribution.cer. Convertir et packager :

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

Le -legacy le flag est important avec OpenSSL 3. Sans lui, les outils d'Apple rejettent le .p12 avec une erreur de mot de passe invalide, même si le mot de passe est correct. Si vous préférez ne pas toucher à OpenSSL, le Générateur de certificats iOS fait la même chose dans le navigateur.

Profil de provisionnement et clé API

Dans le portail Apple Developer, créez un profil App Store pour votre bundle ID utilisant le nouveau certificat et téléchargez le .mobileprovision. Dans App Store Connect, créez une clé API avec le rôl’App Manager et téléchargez le .p8; notez le Key ID et l'Issuer ID. Le Guide de build iOS affiche chaque écran.

Vous voulez inspecter un profil sur Linux ? openssl smime -inform der -verify -noverify -in profile.mobileprovision affiche le plist intégré.

4) Sauvegardez les identifiants dans 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

Ou lancez bunx @capgo/cli@latest build init --platform ios pour la version guidée. Sur Linux, l'étape de la clé App Store Connect est manuelle ; tout le reste est géré par des prompts.

Si Apple rejette la clé avec une erreur d'authentification, synchronisez votre horloge. Le JWT est signé avec l'heure locale et Apple rejette les tokens dont le décalage est trop important :

timedatectl status
sudo timedatectl set-ntp true

5) Demander le build

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

Le préparé ios/ du projet est envoyé, Capgo exécute pod install, archive avec Xcode, signe avec votre certificat et diffuse les logs vers votre terminal. Avec la clé API configurée, le build est soumis à TestFlight une fois terminé. Installez l'app TestFlight sur un iPhone pour l'utiliser.

Les builds qui échouent peuvent être diagnostiqués automatiquement en ajoutant --ai-analytics; le le diagnostic de build par IA qui lit le log Xcode et explique la correction.

6) Builds ad hoc pour les testeurs sans TestFlight

Pour un appareil de QA enregistré par UDID, utilisez un profil Ad Hoc et conservez l'IPA comme artefact :

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

Le CLI affiche un lien de téléchargement à durée limitée. Ajoutez --output-record build.json pour sauvegarder le lien et un code QR pour un testeur.

7) Automatisez depuis un runner CI Linux

Les mêmes commandes s'exécutent sur n'importe quelle CI Linux. Voici un exemple 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 }}

Les identifiants enregistrés à l'étape 4 sont stockés dans Capgo, le runner n'a donc besoin que du token. Sinon, exportez une CI .env par bunx @capgo/cli@latest build credentials manage and pass the values as secrets; see la gestion des identifiants.

8) Itération quotidienne sans builds natifs

Une fois le build TestFlight disponible, la plupart des changements sont des changements web. Poussez-les avec Capgo Live Updates:

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

Réservez build request pour l'ajout de plugins, les changements de permissions, les modifications d'icônes et les mises à niveau Capacitor.

Pièges sous Linux

• Oubli cap sync ios: l'IPA affiche l'ancienne UI. Synchronisez avant chaque requête.
• ios/ dans .gitignore: les CLI sont envoyés depuis le disque, donc le build réussit, mais vos collègues et la CI n'auront pas le projet natif. Commitez-le.
• .p12 mot de passe rejeté: régénérez avec -legacy.
• Échec de l'authentification Apple: dérive de l'horloge. Activez NTP.
• Plugin ajouté, oubli du rebuild natif: l'ajout d'un plugin Capacitor modifie le binaire natif. Lancez un nouveau build cloud et une publication sur les stores avant de déployer des changements web qui l'utilisent.

Résumé

Linux ne peut pas exécuter Xcode, mais ce n'est pas nécessaire. Générez ios/ avec Capacitor, créez les certificats de build avec OpenSSL, et laissez Capgo Build compiler, signer et envoyer vers TestFlight. Grâce aux Live Updates pour la couche web, une équipe travaillant uniquement sur Linux déploie sur iOS aussi régulièrement que sur Android. Pour la configuration complète de l'environnement, lisez le développement Capacitor sur Linux.