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