CI/CD iOS sans Mac local : brancher un runner GitHub Actions auto-hébergé

Pourquoi un runner auto-hébergé bat le runner macOS hébergé GitHub pour les builds iOS

Les runners macOS hébergés par GitHub Actions évitent en théorie la maintenance matérielle, mais en production plusieurs contraintes difficiles à contourner apparaissent — surtout pour la compilation Xcode et la signature de code iOS.

Premier point : temps d'attente. Le pool macOS GitHub est bien plus petit que Linux ; aux heures de pointe (UTC 12–20, heures ouvrées APAC), runs-on: macos-latest attend souvent 8–15 min, parfois 20+ — plus long qu'un Clean Build de 6 min.

Deuxième point : version Xcode incontrôlable. Le tag macos-latest bascule silencieusement (ex. Xcode 15 → 16), cassant des builds ; il faut alors ajouter xcode-select et gérer la compatibilité majeure.

Troisième point : quota gratuit vite épuisé. Un Runner macOS compte 10× un Runner Linux (doc GitHub) ; 2 000 min/mois gratuites = 200 min macOS — un cycle d'itération dense déclenche vite la facturation.

Un Runner auto-hébergé sur votre Mac évite ces trois points : toujours en ligne, version Xcode sous votre contrôle, temps d'exécution non facturé. Seul prérequis : une machine macOS permanente — c'est précisément ce que cet article résout.

Préparation : activer le nœud Mac cloud et l'environnement de base

Avant tout branchement CI/CD iOS, il vous faut un macOS accessible en SSH, 24 h/24. Exemple : Mac mini M4 dédié VPSRox (ou Mac mini / Mac Studio physique) — livrable en 5 minutes après paiement.

Accès SSH et Xcode Command Line Tools

1. 01
   Configurer l'authentification par clé SSH

   Copiez l'IP publique depuis la console, puis exécutez en local :

   ssh-copy-id -i ~/.ssh/id_ed25519.pub user@<IP-du-nœud>

   Ensuite, désactivez la connexion par mot de passe (PasswordAuthentication no) pour limiter les attaques par force brute.

2. 02
   Installer Xcode Command Line Tools

   xcode-select --install

   Pour Xcode GUI complet (Archive), téléchargez le .xip sur developer.apple.com/downloads, extrayez vers /Applications/ et basculez le chemin :

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

3. 03
   Installer Homebrew

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Après installation, ajoutez /opt/homebrew/bin au PATH comme indiqué, dans ~/.zprofile.

4. 04
   Vérifier la chaîne de build Xcode

   xcodebuild -version

   Vérifiez la version Xcode et le Build Version affichés ; vous pourrez ensuite verrouiller la version via la variable d'environnement XCODE_VERSION dans le YAML.

Installer et enregistrer le Runner auto-hébergé GitHub Actions

Le paquet Runner auto-hébergé de GitHub lance sur le Mac un démon en polling qui récupère les jobs localement à chaque workflow — sans ouvrir de port entrant sur la machine.

Obtenir le jeton d'enregistrement dans le dépôt GitHub

Dépôt cible → Settings → Actions → Runners → New self-hosted runner, plateforme macOS ; copiez la commande de téléchargement et le jeton (validité 1 h).

1. 01
   Télécharger et extraire le Runner

   mkdir actions-runner && cd actions-runner

   curl -o actions-runner-osx-arm64-2.319.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.319.1/actions-runner-osx-arm64-2.319.1.tar.gz

   tar xzf ./actions-runner-osx-arm64-2.319.1.tar.gz

   Choisissez le paquet osx-arm64 (Apple Silicon) ; la version exacte figure sur la page GitHub.

2. 02
   Enregistrer le Runner

   ./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token <TOKEN> --name mac-m4-vpsrox --labels mac,xcode16,ios

   Les labels personnalisés --labels serviront ensuite dans runs-on du YAML pour router précisément vers cette machine.

3. 03
   Installer comme service launchd (démarrage auto)

   ./svc.sh install

   ./svc.sh start

   launchd relance automatiquement le Runner après connexion. Vérifier l'état : ./svc.sh status.

Cibler le Runner auto-hébergé dans le YAML du workflow

Après enregistrement, remplacez runs-on dans .github/workflows/ios-ci.yml par votre label personnalisé :

jobs:
  build:
    runs-on: [self-hosted, mac, xcode16]
    steps:
      - uses: actions/checkout@v4
      - name: Show Xcode version
        run: xcodebuild -version

Configurer l'environnement de build Xcode et la gestion des dépendances

Un build iOS propre exige généralement trois choses : récupération des dépendances, cache de compilation et isolation du chemin DerivedData.

CocoaPods vs Swift Package Manager

Si le projet utilise CocoaPods, installez-le une fois sur la machine Runner :

sudo gem install cocoapods

Dans l'étape CI :

- name: Install CocoaPods
  run: pod install --repo-update
  working-directory: ./ios

Avec Swift Package Manager, Xcode résout les dépendances au premier build. Pour accélérer les CI suivantes, mettez en cache le résultat de résolution SPM dans le job :

- uses: actions/cache@v4
  with:
    path: ~/Library/Developer/Xcode/DerivedData
    key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}

Isolation du chemin DerivedData

Si plusieurs projets buildent en parallèle sur le même Runner, le chemin DerivedData par défaut entre en conflit. Spécifiez-le explicitement dans xcodebuild :

xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -sdk iphoneos \
  -configuration Release \
  -derivedDataPath ./DerivedData \
  clean build

Réglage des paramètres de build parallèle

Le Mac mini M4 dispose de 10 cœurs CPU (4 performance + 6 efficacité) ; Xcode fixe en général la concurrence au nombre de cœurs. Sur de gros projets, abaissez-la légèrement pour limiter la pression mémoire :

defaults write com.apple.dt.Xcode IDEBuildOperationMaxNumberOfConcurrentCompileTasks 6

Sur un projet SwiftUI de 80 fichiers Swift, mesuré sur un nœud M4 avec 16 Go de RAM : Clean Build en environ 4 min 12 s, sans pression de swap.

Signature de code et trousseau : workflow complet Archive

La signature de code est l'étape la plus fragile du CI/CD iOS. En CI sans interface graphique, le comportement par défaut du trousseau macOS diffère de l'environnement de développement — une gestion explicite du trousseau est indispensable.

Comparatif des deux approches de signature dominantes

Approche p12 manuelle : créer un trousseau temporaire

En CI, l'approche la plus sûre est de créer un trousseau temporaire par job et de le supprimer après le build, pour éviter les identifiants résiduels :

# Create a temporary keychain
security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
security default-keychain -s build.keychain
security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
security set-keychain-settings -t 3600 -u build.keychain

# Import signing certificate
security import "$CERTIFICATE_P12_PATH" \
  -k build.keychain \
  -P "$P12_PASSWORD" \
  -T /usr/bin/codesign \
  -T /usr/bin/xcodebuild

# Allow xcodebuild to access the key without UI prompt
security set-key-partition-list \
  -S apple-tool:,apple: \
  -s -k "$KEYCHAIN_PASSWORD" build.keychain

KEYCHAIN_PASSWORD, P12_PASSWORD, etc. doivent être dans GitHub Repository Secrets, référencés via ${{ secrets.KEYCHAIN_PASSWORD }} — jamais en dur dans le YAML.

Exécuter Archive et exporter l'IPA

Archive → Export se fait en deux temps : xcodebuild archive pour le .xcarchive, puis -exportArchive pour l'IPA.

# Step 1: Archive
xcodebuild archive \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -sdk iphoneos \
  -archivePath ./build/MyApp.xcarchive \
  CODE_SIGN_IDENTITY="Apple Distribution: Your Name (XXXXXXXX)" \
  DEVELOPMENT_TEAM="XXXXXXXX"

# Step 2: Export IPA
xcodebuild -exportArchive \
  -archivePath ./build/MyApp.xcarchive \
  -exportOptionsPlist ExportOptions.plist \
  -exportPath ./build/

ExportOptions.plist configure l'export : method (app-store / ad-hoc), teamID, signingStyle. Exportez une fois dans Xcode GUI et réutilisez le fichier généré comme modèle.

Intégrer fastlane pour l'upload automatique TestFlight

Une fois l'IPA générée, poussez-la vers TestFlight via fastlane pilot (upload_to_testflight) — stable, authentification par clé API App Store Connect, sans mot de passe Apple ID.

Installer fastlane

Bundler est recommandé pour verrouiller la version fastlane et éviter les conflits globaux :

# In project root, create Gemfile
source "https://rubygems.org"
gem "fastlane"

Puis bundle install ; appelez fastlane via bundle exec fastlane ....

Configurer la clé API App Store Connect

App Store Connect → Users and Access → Integrations → App Store Connect API : créez une clé API, téléchargez le .p8, notez Key ID et Issuer ID.

Définir les variables suivantes dans GitHub Secrets :

• ASC_API_KEY_ID : ID de la clé API
• ASC_API_ISSUER_ID：Issuer ID
• ASC_API_KEY_CONTENT：.p8 Contenu du fichier encodé en Base64

Exemple de configuration Fastfile

lane :beta do
  api_key = app_store_connect_api_key(
    key_id: ENV["ASC_API_KEY_ID"],
    issuer_id: ENV["ASC_API_ISSUER_ID"],
    key_content: Base64.decode64(ENV["ASC_API_KEY_CONTENT"])
  )

  upload_to_testflight(
    api_key: api_key,
    ipa: "./build/MyApp.ipa",
    skip_waiting_for_build_processing: true
  )
end

Appeler depuis le YAML GitHub Actions :

- name: Upload to TestFlight
  env:
    ASC_API_KEY_ID: ${{ secrets.ASC_API_KEY_ID }}
    ASC_API_ISSUER_ID: ${{ secrets.ASC_API_ISSUER_ID }}
    ASC_API_KEY_CONTENT: ${{ secrets.ASC_API_KEY_CONTENT }}
  run: bundle exec fastlane beta

Dépannage centralisé des erreurs courantes du trousseau

Les messages d'erreur de signature de code sont souvent vagues ; voici les cas les plus fréquents en CI sans interface, avec cause racine et solution.

Astuce de débogage : voir la commande de signature complète dans les logs de build

Ajoutez | xcpretty -r json-compilation-database après xcodebuild, ou supprimez xcpretty pour les logs bruts ; cherchez CodeSign pour voir la commande réelle — plus informatif que le panneau d'erreur Xcode.

Une autre commande de débogage utile :

codesign -dv --verbose=4 ./build/MyApp.xcarchive/Products/Applications/MyApp.app

Inspectez directement la signature embarquée dans .app pour vérifier la chaîne de certificats.

Comparatif Jenkins Agent : migration et arbitrages

Si votre équipe dispose déjà d'une infrastructure Jenkins, ou si la politique de sécurité interdit de pousser le code sur GitHub, Jenkins sur Mac est une alternative courante. Les différences clés se jouent sur plusieurs dimensions.

Migration depuis Jenkins : sh 'xcodebuild ...' se transpose quasi 1:1 en run: GitHub Actions. Écarts majeurs : déclencheurs (when { branch ... } → on: push: branches:) et concurrence (lockable-resources → concurrency:).

Prérequis commun aux deux approches : un Mac physique en ligne en permanence, avec une version macOS fixe, comme hôte Agent/Runner. C'est la base de la stabilité du pipeline — surcharge thermique ou dérive de version, et le CI devient imprévisible.

Le vrai blocage des petites équipes n'est souvent pas le choix d'outil, mais : pas de Mac physique dédié au CI. Un MacBook bureau avec 8 Go de RAM throttle en gros build ; un nouveau Mac mini coûte cher en amont plus hébergement et maintenance.

Mac cloud dédié : solution de build fixe sans machine physique propre

Face à ce dilemme, louer à la demande un Mac cloud dédié mérite une évaluation sérieuse — pas d'investissement matériel initial, tout en obtenant un nœud de build macOS dédié à environnement stable.

Exemple avec un Mac mini M4 VPSRox : 16 Go de mémoire unifiée + 256 Go NVMe SSD, bande passante 1 Gbps dédiée, à partir de 21,8 $/jour, livraison automatique en 1–5 minutes, sans engagement.

Du point de vue CI/CD, c'est comme louer un Mac mini toujours en ligne à puissance dédiée ; les possibilités sont identiques à une machine physique locale :

• Installer toute version Xcode (via xcodes) et verrouiller l'environnement de build
• Enregistrer comme Runner auto-hébergé GitHub Actions ou Jenkins Agent — toutes les étapes de cet article s'appliquent telles quelles
• CPU 10 cœurs M4 et Neural Engine 38 TOPS — meilleures perfs sur projets avec compilation de modèles Core ML
• Extension Thunderbolt 5 pour un cluster de build privé multi-Mac mini (grandes équipes)

Vs Runner hébergé GitHub : à forte fréquence (30+ builds/jour), la location journalière coûte souvent moins que le dépassement macOS ; vs achat d'un Mac mini : pas d'investissement initial, durée ajustable selon la phase du projet.

Cinq nœuds mondiaux (Singapour, Tokyo, Séoul, Hong Kong, côte est des États-Unis) — choisissez le plus proche de votre équipe pour réduire la latence de git fetch et des téléchargements de dépendances.