Aller au contenu principal
Tutoriel

Compilez une app iOS depuis Linux avec Capacitor et Capgo Build

Déployez un build iOS signé sur TestFlight depuis Ubuntu, Fedora ou n’importe quelle machine Linux : générez le projet ios/ avec Capacitor, créez les certificats avec OpenSSL, et laissez Capgo Build compiler et soumettre sans Mac.

Compiler une app iOS depuis Linux avec Capacitor et Capgo Illustration du blog sur le build Capgo

Linux est un environnement idéal pour développer des apps Capacitor, et Android s’y déploie sans compromis. iOS fait exception : Xcode et les outils de signature d’Apple ne fonctionnent que sur macOS. La solution n’est pas 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 aborde les spécificités de Linux : certificats OpenSSL, shell Linux et CI depuis 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.

Le CLI effectue l'upload du 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 se compile en local (n'importe quel framework).
  • Node 20+ ou Bun sur Linux.
  • Un abonnement Apple Developer Program.
  • OpenSSL (installé par défaut sur la quasi-totalité des 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, vos icônes et vos 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 aux plugins. Capgo compile ce qui se trouve dans ios/, donc un projet non synchronisé embarque votre ancienne interface.

3) Créer les éléments de signature sans Mac

Il vous faut trois choses : un certificat Apple Distribution au format .p12, un profil de provisionnement App Store et une clé API App Store Connect. Aucun ne nécessite Keychain Access.

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, puis téléchargez distribution.cer. Convertissez et créez le bundle :

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 l’option est importante avec OpenSSL 3. Sans elle, les outils 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, 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 en utilisant le nouveau certificat, puis 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.

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

4) Enregistrez 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 demandé via 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 profil préparé ios/ projet préparé est envoyé, Capgo s'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'application 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 QA enregistré par UDID, utilisez un profil Ad Hoc et conservez l’IPA en tant qu’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 enregistrer le lien et un QR code destiné à un testeur.

7) Automatiser depuis un runner CI Linux

Les mêmes commandes s'exécutent sur n'importe quel CI Linux. Exemple avec 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 un CI .env par bunx @capgo/cli@latest build credentials manage et passez les valeurs en tant que secrets ; voir la gestion des identifiants.

8) Itération quotidienne sans builds natifs

Une fois le build TestFlight créé, la plupart des modifications sont des modifications web. Publiez-les avec Live Updates Capgo:

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

À réserver 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: le CLI envoie depuis le disque, donc le build passe quand même, 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.
  • L'authentification Apple a échoué: dérive de l'horloge. Activez NTP.
  • Plugin ajouté, rebuild natif oublié: l’ajout d’un plugin Capacitor modifie le binaire natif. Lancez un nouveau build cloud et une soumission au store avant de déployer des modifications web qui l’appellent.

Résumé

Linux ne peut pas exécuter Xcode, mais il n’en a pas besoin. Générez ios/ avec Capacitor, les certificats de build avec OpenSSL, et laissez Capgo Build compiler, signer et envoyer sur TestFlight. Avec Live Update pour la couche web, une équipe 100 % Linux déploie iOS aussi facilement qu’Android. Pour la configuration complète de l’environnement, lisez Développement Capacitor sur Linux.

Live updates pour les apps Capacitor

Lorsqu'un bug de la couche web est en ligne, déployez le correctif via Capgo au lieu d'attendre des jours l'approbation des stores. Les utilisateurs reçoivent la mise à jour en arrière-plan, tandis que les changements natifs suivent le circuit de validation habituel.

Les derniers articles du blog

Capgo vous offre les meilleures informations pour créer une application mobile vraiment professionnelle.