専用のMacビルドサーバーにfastlaneをセットアップする

最初に必要なもの

• Xcode、管理者権限、HomebrewのあるMac。
• そのMac上のCIエージェント：GitHub Actions、GitLab、Buildkite、Jenkins、CircleCIのいずれか。
• APIキーを作成する権限のあるApp Store Connectアカウント。
• match用のプライベートなGitリポジトリ、またはGoogle CloudかS3のバケット。

1. fastlaneをインストールする

2026年10月に読んだfastlaneのドキュメントは、Bundlerを推奨しています。Ruby 3.2以降をサポートし、3.3以降を推奨しています。macOSのシステムRubyは使わないよう勧めています。rbenvなどのバージョンマネージャーで最新のRubyをインストールし、プロジェクトにGemfileを追加します。

source "https://rubygems.org"

gem "fastlane"

gem install bundler
bundle update
git add Gemfile Gemfile.lock

BundlerはGemfile.lockでfastlaneのバージョンを固定します。どのマシンでも、どのCIの実行でも同じバージョンが使われます。bundle exec fastlaneとして実行します。

ビルドサーバーが1台だけなら、Homebrewのほうが簡単です。Ruby込みで入ります。

brew install fastlane

プロジェクトごとにどちらか1つを選んでください。両方を混ぜると、1台のマシンにfastlaneが2つのバージョンで入ってしまいます。

2. App Store Connect APIキーを作成する

fastlaneは、Apple IDでのログインよりAPIキーを推奨しています。2段階認証のプロンプトがなく、速く、より確実だからです。App Store Connectで「ユーザとアクセス」、「統合」、「App Store Connect API」の順に開きます。チームキーを作成します。fastlaneによると、プロビジョニングの呼び出しにはチームキーが必要です。動作する範囲で最小の役割を与えてください。発行者IDとキーIDを控えます。.p8ファイルはすぐにダウンロードしてください。Appleがダウンロードを許すのは一度だけです。

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

キーはビルド用のMacか、CIのシークレットストアに保管してください。決してコミットしないでください。

3. matchを開発マシンから一度だけセットアップする

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

match initは証明書の保存先を尋ね、Matchfileを書き出します。続く2つのコマンドで証明書とプロファイルを作成し、暗号化してその保存先に保存します。強力なパスフレーズを選んでください。CIはそれをMATCH_PASSWORD変数から読み取ります。

fastlaneは、どのCIシステムでもreadonlyモードを推奨しています。そうすればCIは既存のものをダウンロードするだけで、何かを作成したり失効させたりすることはありません。

4. レーンを書く

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は一時的なキーチェーンを作成し、matchをreadonlyに切り替え、ログとテスト結果のパスを設定します。動作するのは、fastlaneがCIでの実行を検出したときだけです。検出されない場合はforce: trueを渡します。ビルド処理の待機を省くとジョブは早く終わりますが、fastlaneによると外部テスターへの配布も省かれます。

5. CIから呼び出す

どのCIシステムでも、実行するシェルの行は同じです。シークレットはリポジトリではなく、CIに保存してください。

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

GitHub Actionsでは、これらの行をrunステップに書き、シークレットはenvとして渡します。MacRunのMacには、GitHub Actionsのrunnerソフトウェアがインストール済みです。ワークフロー全体はGitHub ActionsでのiOSセットアップガイドにあります。GitLab、Buildkite、CircleCIでは、同じ行をジョブのスクリプトに書きます。Jenkinsではshステップを使います。

再起動しても動き続ける仕組み

fastlaneはサービスではありません。CIエージェントのジョブの中で動きます。再起動後に戻る必要があるのは、エージェントとそのログインセッションです。GitLab RunnerとBuildkiteのガイドのように、エージェントをLaunchAgentとして設定し、自動ログインと組み合わせます。setup_ciの一時的なキーチェーンは毎回作り直されます。再起動後にログインキーチェーンがロックされていても、止まることはありません。

よくあるエラーと対処法

以下はfastlaneが記載しているものです。

• CIで奇妙なエンコーディングのエラーやクラッシュが起きる。fastlaneにはUTF-8のロケールが必要です。LANGとLC_ALLをen_US.UTF-8に設定してください。
• ジョブが2段階認証のプロンプトで止まる。APIキーを使ってください。Apple IDを使う場合は、SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FAを設定すれば、止まらずにすぐ失敗します。
• matchがCIで新しい証明書を作ろうとする。readonlyを使うか、先にsetup_ciを呼び出してください。
• matchがリポジトリをcloneできない。GitHubは1つのデプロイキーを2つのリポジトリで使うことを認めていません。読み取り専用のマシンアカウント、git_private_key、MATCH_GIT_BASIC_AUTHORIZATIONのいずれかを使ってください。
• プロファイルはインストールされているのに、Xcodeから見えない。Xcode 16でプロファイルのフォルダが移動しました。fastlaneは選択されているXcodeに従うので、Xcodeが2つあるマシンではmatchの前にxcode_selectを実行してください。

専用Macが役立つ理由

build_appとrun_testsはXcodeのビルドです。DerivedDataとインストール済みのgemを保持するマシンなら、ずっと速くなります。Xcode 26.6でWikipediaのiOSアプリを使った当社のベンチマークでは、クリーンビルドがM6で86秒でした。GitHubホスト型のmacos-26 runnerでは183秒でした。小さな変更後のジョブは、ウォームで27秒、新規で269秒でした。

ビルドサーバーが不要な場合

TestFlightへの配信が週1回なら、ホスト型runnerかXcode Cloudのほうが手間は少なく済みます。その比較はXcode Cloudの代替ガイドをご覧ください。MacRunがしないことにも注意してください。当社はコード署名を管理しません。このページのように、matchはお客様自身で実行します。SLAも提供していません。

ビルドサーバーを用意しますか。すべてのティアは料金ページに、接続方法はセットアップドキュメントにあります。