Configurer fastlane sur un serveur de build Mac dédié

Ce qu’il vous faut d’abord

• Un Mac avec Xcode, accès administrateur et Homebrew.
• Un agent CI sur ce Mac : GitHub Actions, GitLab, Buildkite, Jenkins ou CircleCI.
• Un compte App Store Connect avec le droit de créer des clés API.
• Un dépôt Git privé pour match, ou un bucket Google Cloud ou S3.

1. Installez fastlane

La documentation de fastlane, lue en octobre 2026, préfère Bundler. Elle prend en charge Ruby 3.2 ou plus récent, et préfère 3.3 ou plus récent. Elle déconseille le Ruby système de macOS. Installez un Ruby récent avec un gestionnaire de versions comme rbenv. Ajoutez ensuite un Gemfile au projet :

source "https://rubygems.org"

gem "fastlane"

gem install bundler
bundle update
git add Gemfile Gemfile.lock

Bundler fige la version de fastlane dans Gemfile.lock. Chaque machine et chaque run CI obtiennent la même. Lancez-le avec bundle exec fastlane.

Sur un seul serveur de build, la voie la plus simple est Homebrew. Il apporte son propre Ruby :

brew install fastlane

Choisissez une seule voie par projet. C’est en les mélangeant qu’on se retrouve avec deux versions de fastlane sur une machine.

2. Créez une clé API App Store Connect

fastlane recommande les clés API plutôt que les connexions par identifiant Apple : pas de code à deux facteurs, plus de vitesse, plus de fiabilité. Dans App Store Connect, ouvrez Users and Access, puis Integrations, puis App Store Connect API. Créez une Team Key. fastlane précise que les appels de provisionnement demandent une clé d’équipe. Donnez-lui le rôle le plus restreint qui fonctionne. Notez l’Issuer ID et le Key ID. Téléchargez tout de suite le fichier .p8, car Apple ne le laisse télécharger qu’une fois.

mkdir -p ~/.appstoreconnect
mv ~/Downloads/AuthKey_ABC123XYZ.p8 ~/.appstoreconnect/
chmod 600 ~/.appstoreconnect/AuthKey_ABC123XYZ.p8

Gardez la clé sur le Mac de build ou dans le coffre à secrets de votre CI. Ne la committez jamais.

3. Configurez match une fois, depuis une machine de développement

bundle exec fastlane match init
bundle exec fastlane match development
bundle exec fastlane match appstore

match init demande où stocker les certificats et écrit un Matchfile. Les deux commandes suivantes créent les certificats et les profils, et les enregistrent chiffrés dans ce stockage. Choisissez une phrase de passe solide. La CI la lit dans la variable MATCH_PASSWORD.

fastlane recommande le mode readonly sur toutes les CI. La CI ne fait alors que télécharger ce qui existe, et ne crée ni ne révoque jamais rien.

4. Écrivez les lanes

default_platform(:ios)

platform :ios do
  lane :test do
    run_tests(
      scheme: "MyApp",
      devices: ["iPhone 17"],
      result_bundle: true
    )
  end

  lane :beta do
    setup_ci
    api_key = app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_filepath: ENV["ASC_KEY_PATH"]
    )
    match(type: "appstore", readonly: is_ci, api_key: api_key)
    increment_build_number(
      build_number: latest_testflight_build_number(api_key: api_key) + 1
    )
    build_app(scheme: "MyApp")
    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: true)
  end
end

setup_ci crée un trousseau temporaire, passe match en readonly, et règle les chemins des logs et des résultats de test. Il n’agit que lorsque fastlane détecte une exécution en CI. Si la vôtre n’est pas détectée, passez force: true. Sauter le traitement du build termine le job plus tôt. Mais fastlane précise que cela saute aussi la distribution aux testeurs externes.

5. Appelez-le depuis la CI

Toutes les CI lancent les mêmes lignes shell. Stockez les secrets dans votre CI, pas dans le dépôt.

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
bundle install
bundle exec fastlane beta
# needs MATCH_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID and ASC_KEY_PATH set as CI secrets

Sur GitHub Actions, ces lignes vont dans une étape run, avec les secrets passés en env. Un Mac MacRun arrive avec le logiciel du runner GitHub Actions déjà installé. Notre guide de configuration iOS sur GitHub Actions montre un workflow complet. Sur GitLab, Buildkite ou CircleCI, mettez les mêmes lignes dans le script du job. Sur Jenkins, utilisez une étape sh.

Comment tout cela survit aux redémarrages

fastlane n’est pas un service. Il tourne dans le job de votre agent CI. Ce qui doit survivre à un redémarrage, c’est l’agent et sa session. Configurez l’agent comme LaunchAgent avec la connexion automatique, comme dans nos guides GitLab Runner et Buildkite. Le trousseau temporaire de setup_ci est recréé à chaque exécution. Un trousseau de session verrouillé après un redémarrage ne peut donc pas le bloquer.

Erreurs courantes et solutions

Elles sont documentées par fastlane.

• Des erreurs d’encodage bizarres ou des plantages en CI. fastlane a besoin d’une locale UTF-8. Réglez LANG et LC_ALL sur en_US.UTF-8.
• Le job reste bloqué sur une demande de code à deux facteurs. Utilisez la clé API. Avec un identifiant Apple, réglez SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA pour qu’il échoue vite à la place.
• match essaie de créer de nouveaux certificats en CI. Utilisez readonly, ou appelez d’abord setup_ci.
• match n’arrive pas à cloner son dépôt. GitHub n’accepte pas une même deploy key sur deux dépôts. Utilisez un compte machine en lecture seule, ou git_private_key, ou MATCH_GIT_BASIC_AUTHORIZATION.
• Les profils sont installés mais Xcode ne les voit pas. Xcode 16 a déplacé le dossier des profils. fastlane suit le Xcode sélectionné, donc lancez xcode_select avant match sur les machines qui ont deux Xcode.

Pourquoi un Mac dédié aide

build_app et run_tests sont des builds Xcode. Sur une machine qui garde le DerivedData et les gems installées, ils sont bien plus rapides. Dans notre benchmark sur l’app iOS Wikipedia avec Xcode 26.6, un build propre a pris 86 secondes sur un M6. Il a pris 183 secondes sur un runner macos-26 hébergé par GitHub. Un job après un petit changement a pris 27 secondes à chaud, contre 269 à froid.

Quand vous n’avez pas besoin d’un serveur de build

Si vous envoyez sur TestFlight une fois par semaine, un runner hébergé ou Xcode Cloud demande moins de travail. Voir notre guide des alternatives à Xcode Cloud pour ce compromis. Notez aussi ce que MacRun ne fait pas. Nous ne gérons pas la signature de code pour vous. Vous lancez match vous-même, comme sur cette page. Nous ne proposons pas non plus de SLA.

Prêt pour un serveur de build ? Les tarifs listent tous les modèles, et la documentation d’installation montre comment vous connecter.