fastlane auf einem dedizierten Mac-Build-Server einrichten

Was Sie vorher brauchen

• Einen Mac mit Xcode, Admin-Zugriff und Homebrew.
• Einen CI-Agent auf diesem Mac: GitHub Actions, GitLab, Buildkite, Jenkins oder CircleCI.
• Ein App-Store-Connect-Konto mit dem Recht, API-Schlüssel anzulegen.
• Ein privates Git-Repo für match oder einen Bucket in Google Cloud oder S3.

1. fastlane installieren

Die Doku von fastlane, gelesen im Oktober 2026, bevorzugt Bundler. Sie unterstützt Ruby 3.2 oder neuer und empfiehlt 3.3 oder neuer. Vom System-Ruby von macOS rät sie ab. Installieren Sie ein aktuelles Ruby mit einem Versionsmanager wie rbenv. Fügen Sie dem Projekt dann ein Gemfile hinzu:

source "https://rubygems.org"

gem "fastlane"

gem install bundler
bundle update
git add Gemfile Gemfile.lock

Bundler legt die fastlane-Version in Gemfile.lock fest. Jede Maschine und jeder CI-Lauf bekommt dieselbe. Starten Sie es mit bundle exec fastlane.

Der einfachere Weg auf einem einzelnen Build-Server ist Homebrew. Es bringt sein eigenes Ruby mit:

brew install fastlane

Wählen Sie einen Weg pro Projekt. Wer beide mischt, hat am Ende zwei fastlane-Versionen auf einer Maschine.

2. Einen App-Store-Connect-API-Schlüssel anlegen

fastlane empfiehlt API-Schlüssel statt Anmeldungen mit Apple ID: keine Zwei-Faktor-Abfrage, mehr Tempo, mehr Zuverlässigkeit. Öffnen Sie in App Store Connect Users and Access, dann Integrations, dann App Store Connect API. Legen Sie einen Team Key an. Laut fastlane brauchen Aufrufe für das Provisioning einen Team Key. Geben Sie ihm die kleinste Rolle, die funktioniert. Notieren Sie Issuer ID und Key ID. Laden Sie die .p8-Datei sofort herunter. Apple erlaubt den Download nur einmal.

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

Bewahren Sie den Schlüssel auf dem Build-Mac oder im Secret-Speicher Ihrer CI auf. Committen Sie ihn nie.

3. match einmalig auf einem Entwicklerrechner einrichten

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

match init fragt, wo die Zertifikate liegen sollen, und schreibt ein Matchfile. Die nächsten zwei Befehle legen Zertifikate und Profile an und speichern sie verschlüsselt in diesem Speicher. Wählen Sie eine starke Passphrase. Die CI liest sie aus der Variable MATCH_PASSWORD.

fastlane empfiehlt den readonly-Modus auf jedem CI-System. Dann lädt die CI nur herunter, was existiert, und legt nie etwas an oder widerruft etwas.

4. Die Lanes schreiben

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 legt einen temporären Schlüsselbund an, schaltet match auf readonly und richtet Pfade für Logs und Testergebnisse ein. Es greift nur, wenn fastlane einen CI-Lauf erkennt. Wird Ihrer nicht erkannt, übergeben Sie force: true. Wer die Build-Verarbeitung überspringt, beendet den Job früher. Laut fastlane entfällt dann aber auch die Verteilung an externe Tester.

5. Aus der CI aufrufen

Jedes CI-System führt dieselben Shell-Zeilen aus. Speichern Sie die Secrets in Ihrer CI, nicht im Repo.

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

In GitHub Actions kommen diese Zeilen in einen run-Step, die Secrets übergeben Sie als env. Auf einem MacRun-Mac ist die Runner-Software für GitHub Actions schon installiert. Unser Leitfaden zum iOS-Setup mit GitHub Actions zeigt einen vollständigen Workflow. In GitLab, Buildkite oder CircleCI setzen Sie dieselben Zeilen in das Script des Jobs. In Jenkins nutzen Sie einen sh-Step.

Wie das Neustarts übersteht

fastlane ist kein Dienst. Es läuft im Job Ihres CI-Agents. Einen Neustart überstehen müssen der Agent und seine Anmeldesitzung. Richten Sie den Agent als LaunchAgent mit automatischer Anmeldung ein, wie in unseren Leitfäden zu GitLab Runner und Buildkite. Den temporären Schlüsselbund von setup_ci baut jeder Lauf neu auf. Ein gesperrter Anmelde-Schlüsselbund nach einem Neustart kann ihn nicht blockieren.

Häufige Fehler und Lösungen

Diese sind von fastlane dokumentiert.

• Seltsame Encoding-Fehler oder Abstürze in der CI. fastlane braucht eine UTF-8-Locale. Setzen Sie LANG und LC_ALL auf en_US.UTF-8.
• Der Job hängt an einer Zwei-Faktor-Abfrage. Nutzen Sie den API-Schlüssel. Setzen Sie bei einer Apple ID SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA, damit er stattdessen schnell scheitert.
• match versucht in der CI, neue Zertifikate anzulegen. Nutzen Sie readonly oder rufen Sie zuerst setup_ci auf.
• match kann sein Repo nicht klonen. GitHub akzeptiert einen Deploy Key nicht für zwei Repos. Nutzen Sie ein Maschinenkonto mit Lesezugriff, git_private_key oder MATCH_GIT_BASIC_AUTHORIZATION.
• Profile sind installiert, aber Xcode sieht sie nicht. Xcode 16 hat den Ordner für Profile verlegt. fastlane folgt dem ausgewählten Xcode. Führen Sie auf Maschinen mit zwei Xcode-Versionen also xcode_select vor match aus.

Warum ein dedizierter Mac hilft

build_app und run_tests sind Xcode-Builds. Auf einer Maschine, die DerivedData und installierte Gems behält, laufen sie viel schneller. In unserem Benchmark mit der Wikipedia-iOS-App und Xcode 26.6 dauerte ein sauberer Build auf einem M6 86 Sekunden. Auf einem gehosteten macos-26-Runner von GitHub waren es 183 Sekunden. Ein Job nach einer kleinen Änderung dauerte warm 27 Sekunden, frisch 269.

Wann Sie keinen Build-Server brauchen

Liefern Sie einmal pro Woche an TestFlight aus, machen ein gehosteter Runner oder Xcode Cloud weniger Arbeit. Den Vergleich finden Sie in unserem Leitfaden zu Alternativen für Xcode Cloud. Beachten Sie auch, was MacRun nicht macht. Wir verwalten die Code-Signierung nicht für Sie. Sie betreiben match selbst, wie auf dieser Seite. Ein SLA bieten wir auch nicht.

Bereit für einen Build-Server? Unter Preise finden Sie jede Stufe, und die Setup-Doku zeigt, wie Sie sich verbinden.