Pilot (Fastlane): 主要概念、TestFlight、モバイルプロジェクトのビルド管理

Pilot（Fastlane）とは？

Pilot（Fastlane）は、モバイルアプリケーションのベータテストのためのAppleのプラットフォームであるTestFlightとの連携を自動化するFastlaneエコシステムのコンポーネントです。Pilotはビルドのアップロード、テスターの追加、グループ管理、ビルドステータスの追跡など、すべてのルーチン操作を処理します。

Pilotがない場合、ベータ配布プロセスは次のようになります。開発者が手動でApp Store Connectを開き、アプリを選択し、Xcode Organizerを介してIPAをアップロードし、テスターグループを設定して招待状を送信します。TestFlightは、App Storeでの正式リリース前にアプリのベータ版をテスターに配布するためのAppleのサービスです。

App Store Connect Help（2025）によると、外部テスターは最初のビルドインストール前にBeta App Reviewプロセスを通過する必要があり、これには1〜48時間かかります。Pilotはレビューステータスを自動的に追跡し、ビルドが外部テスターグループへの配布準備ができたときにチームに通知します。

テスターへのベータビルドの定期的な配信が必要なプロジェクトにはPilotを使用してください。iOS CI/CDパイプラインの標準ツールであり、予測可能な配信プロセスを保証します。

TestFlight向けPilotの主要機能

Pilotの機能は、ベータビルド管理の完全なライフサイクルをカバーします。バイナリファイルのアップロードから新しいバージョンのテスターへの通知まで、各機能は予測可能な動作と各ステップの詳細なログ記録を備えた個別のコマンドとして実装されています。

TestFlightへのビルドのアップロード

fastlane pilot uploadコマンドはIPAファイルをApp Store Connectにアップロードし、TestFlightに新しいビルドを作成します。Pilotはバイナリファイルの有効性、バージョンの互換性、アプリ識別子を自動的にチェックします。App Store Connectは、ビルドのアップロード、メタデータ、分析、販売レポートを含むアプリケーション管理のためのAppleのプラットフォームです。

アップロード後、PilotはAppleがバイナリファイルを処理するのを待ちます。プロセスはビルドサイズに応じて5〜30分かかります。待機中、Pilotは現在の処理ステータス（Processing、Validating、またはReady）を示すプログレスバーを表示します。処理が成功すると、ビルドはテスターグループに割り当て可能になります。

テスターグループの管理

Pilotは内部テスターグループと外部テスターグループの両方の管理をサポートします。内部テスターはApple Developerチームのメンバーで、Beta App Reviewを経由せずに即座にビルドにアクセスできます。外部テスターはメールで招待されたユーザーで、最初のインストール前にレビューの承認が必要です。

fastlane pilot addコマンドは、メールまたはApple IDでグループに新しいテスターを追加します。Pilotは自動的に招待状を送信し、テスターが招待を受け入れたかどうかを確認します。一括追加の場合は、--testers_file_pathパラメータを使用してファイルからメールのリストを渡すことができ、数百人の参加者からなるテスターグループを初期構築する際に便利です。

# 新しいビルドをTestFlightにアップロードする
fastlane pilot upload --ipa "build/MyApp.ipa"

# グループにテスターを追加する
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Pilotのセットアップと設定

Pilotの設定は個別の設定ファイルを必要とせず、Appfile（共通のFastlaneファイル）またはコマンドライン引数を介して設定を渡します。主要なパラメータには、アプリのapple_id、app_identifier、team_id、およびApp Store Connect APIにアクセスするための認証情報が含まれます。

認証には、PilotはApp Store Connect API Key（推奨方法）またはApple IDの二要素認証を使用します。App Store Connect API KeyはApp Store Connectで生成されるアクセスキーで、パスワードと確認コードを対話的に入力せずにAPIとやり取りできます。

# Appfile — Fastlane共通設定
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Pilotの環境変数
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

app_identifierパラメータはアプリのBundle Identifierを定義し、XcodeプロジェクトとApp Store Connectで指定された識別子と一致する必要があります。apple_idパラメータは二要素認証スキームでの認証に使用され、team_idはアカウントが複数のApple Developerチームにリンクされている場合に開発チームを選択するために使用されます。

Pilotを機能させるには、CI/CD環境でApp Store Connect API Keyを設定する必要があります。キーはApp Store Connect → Users and Access → Keys → Generate API Keyで生成されます。.p8ファイルをCIシステムのシークレットに保存し、APP_STORE_CONNECT_API_KEY_PATH環境変数またはPilotコマンドの--api_key_pathパラメータを介してパスを指定します。

ビルド管理のためのPilotコマンド

Pilotコマンドのセットは、ビルドのアップロード、テスター管理、ステータス表示、メタデータ追跡など、すべてのTestFlightシナリオをカバーします。各コマンドは、CI/CDスクリプトでさらに処理するための構造化されたJSON出力を返します。

ビルドステータスの表示

fastlane pilot buildsコマンドは、バージョン、処理ステータス、アップロード日とともにすべてのアプリビルドのリストを表示します。ビルドステータスは次のいずれかです：Processing（Appleがバイナリファイルを処理中）、Ready（ビルドが配布可能）、Rejected（検証エラーのためビルドが拒否されました）。

# TestFlightの全ビルドリストを表示する
fastlane pilot builds

# テスターグループにビルドを割り当てる
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# 特定のビルドに関する情報を表示する
fastlane pilot build_info --build_number 42

fastlane pilot distributeコマンドは、指定されたテスターグループにビルドを割り当て、通知を送信します。--notifyパラメータは、新しい利用可能なビルドについてテスターにメール通知を送信できるようにします。これは、ベータテスターをテストプロセスに参加させ、フィードバックを迅速化するために重要です。

ビルドメタデータを管理するには、--changelogパラメータを使用します。これは新しいバージョンの変更内容の説明テキストを設定します。このテキストはTestFlightアプリのテスト招待状でテスターに表示されます。各ビルドで主要な変更点、修正されたバグ、新機能を指定することをお勧めします。

CI/CDパイプラインへのPilot統合

CI/CDでのPilotは、iOSアプリ配信パイプラインの最終段階です。GymがIPAをビルドしテストが合格した後、PilotはビルドをTestFlightにアップロードし、テスターグループに配布します。これにより、QAチームはリポジトリへのコミットから数分以内に新しいアプリバージョンを入手できます。

一般的なiOS CI/CDパイプラインには、次のシーケンスが含まれます：Match（証明書）、Gym（IPAビルド）、Pilot（TestFlightへのアップロードと配布）。各段階は前の段階に依存し、有効で署名されたビルドのみがテスターに配信されることを保証します。

# Fastfileの完全パイプライン
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

アップロードコマンドのskip_waitingパラメータを使用すると、CIタスク内でAppleのバイナリファイル処理の完了を待たずに、Pilotがアップロードリクエストを送信し、ビルド識別子を受け取って終了できます。これにより、処理に最大30分かかる可能性があるため、CIランナーでの待機時間を節約してパイプラインを高速化できます。

CIでPilotを正しく機能させるには、App Store Connect APIキーを設定する必要があります。.p8キーファイルをCIシステムの安全なストレージに保存し、APP_STORE_CONNECT_API_KEY_PATH環境変数を介してパスを渡します。Pilotはこのキーを使用して二要素認証なしでAPIに認証し、自動化シナリオに不可欠です。

Pilot使用時の一般的な問題

Pilotを使用する際、開発者は認証エラー、アプリ設定の誤り、Apple側でのバイナリファイル処理の問題に最も頻繁に直面します。Pilotの問題診断は、pilot buildsコマンドを使用してApp Store Connectでビルドステータスを確認することから始まります。

“Your app is not available for testing in TestFlight”エラーは、アプリがApp Store Connectでテスト用に設定されていない場合に発生します。解決策：App Store ConnectでTestFlightセクションを開き、アプリのテストを有効にして、Export Complianceが暗号化タイプに正しく入力されていることを確認します。

“Missing iOS Distribution signing identity”エラーは、キーチェーンにDistribution証明書がないことを示します。解決策：Pilotを呼び出す前にMatchを実行して正しい証明書をダウンロードします。Distribution証明書はDevelopmentとは異なり、TestFlightまたはApp Storeを介した配布を目的としたビルドに署名するために使用されます。

“Invalid Provisioning Profile”エラーの場合、ビルドに選択されたエクスポート方法に誤ったプロファイルが含まれています。解決策：GymがMatchのプロファイルタイプに一致する正しいexport_methodを使用していることを確認します。ビルドがdevelopmentプロファイルで作成された場合、PilotはそれをTestFlightにアップロードできません。app-storeまたはad-hocプロファイルが必要です。