Pilot (Fastlane): Key Concepts, TestFlight, and Build Management for Mobile Projects

What Is Pilot (Fastlane)?

Pilot (Fastlane) is a component of the Fastlane ecosystem for automating work with TestFlight — Apple’s platform for beta testing mobile applications. Pilot handles all routine operations: uploading builds, adding testers, managing groups, and tracking build status.

Without Pilot, the beta distribution process looks like this: the developer manually opens App Store Connect, selects the app, uploads IPA via Xcode Organizer, configures a tester group, and sends invitations. TestFlight is Apple’s service for distributing beta versions of apps to testers before the official release on the App Store.

According to App Store Connect Help (2025), external testers must go through the Beta App Review process before the first build installation — this takes from 1 to 48 hours. Pilot automatically tracks the review status and notifies the team when the build is ready for distribution to external tester groups.

Use Pilot in any project that requires regular delivery of beta builds to testers — it is a standard tool for iOS CI/CD pipelines, ensuring a predictable delivery process.

Main Functions of Pilot for TestFlight

Pilot’s functionality covers the full lifecycle of beta build management: from uploading a binary file to notifying testers about a new version. Each function is implemented as a separate command with predictable behavior and detailed logging of every step.

Uploading Builds to TestFlight

The fastlane pilot upload command uploads the IPA file to App Store Connect and creates a new build in TestFlight. Pilot automatically checks the binary file validity, version compliance, and app identifier. App Store Connect is Apple’s platform for managing applications, including uploading builds, metadata, analytics, and sales reports.

After upload, Pilot waits for Apple to process the binary file — the process takes from 5 to 30 minutes depending on the build size. While waiting, Pilot displays a progress bar with information about the current processing status: Processing, Validating, or Ready. Upon successful processing, the build becomes available for assignment to tester groups.

Managing Tester Groups

Pilot supports managing both internal and external tester groups. Internal testers are members of your Apple Developer team who get access to builds instantly, without going through Beta App Review. External testers are users invited via email, who require review approval before the first installation.

The fastlane pilot add command adds new testers to a group by email or Apple ID. Pilot automatically sends invitations and checks whether the tester has accepted the invite. For bulk addition, you can pass a list of emails from a file using the --testers_file_path parameter, which is convenient when initially building a tester group of hundreds of participants.

# Uploading a new build to TestFlight
fastlane pilot upload --ipa "build/MyApp.ipa"

# Adding a tester to a group
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Pilot Setup and Configuration

Pilot configuration does not require a separate config file — settings are passed through Appfile (the common Fastlane file) or command-line arguments. The main parameters include the app’s apple_id, app_identifier, team_id, and credentials for accessing the App Store Connect API.

For authentication, Pilot uses the App Store Connect API Key (recommended method) or Apple ID two-factor authentication. App Store Connect API Key is an access key generated in App Store Connect that allows interacting with the API without entering a password and confirmation code interactively.

# Appfile — Fastlane common configuration
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Environment variables for Pilot
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

The app_identifier parameter defines the Bundle Identifier of the app, which must match the identifier specified in the Xcode project and App Store Connect. The apple_id parameter is used for authentication in the two-factor scheme, and team_id — for selecting the development team if the account is linked to multiple Apple Developer teams.

For Pilot to work, you need to configure the App Store Connect API Key in the CI/CD environment. The key is generated in App Store Connect → Users and Access → Keys → Generate API Key. Save the .p8 file in CI system secrets and specify the path to it via the APP_STORE_CONNECT_API_KEY_PATH environment variable or the --api_key_path parameter in Pilot commands.

Pilot Commands for Build Management

The set of Pilot commands covers all TestFlight scenarios: uploading builds, managing testers, viewing statuses, and tracking metadata. Each command returns structured JSON output for further processing in CI/CD scripts.

Viewing Build Statuses

The fastlane pilot builds command displays a list of all app builds with version, processing status, and upload date. Build status can be one of: Processing — Apple is processing the binary file, Ready — the build is available for distribution, Rejected — the build was rejected due to validation errors.

# Viewing the list of all builds in TestFlight
fastlane pilot builds

# Assigning a build to a tester group
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# Viewing information about a specific build
fastlane pilot build_info --build_number 42

The fastlane pilot distribute command assigns the build to specified tester groups and sends notifications. The --notify parameter enables sending email notifications to testers about a new available build — this is critical for engaging beta testers in the testing process and speeding up feedback.

To manage build metadata, use the --changelog parameter, which sets the description text of changes in the new version. This text is displayed to testers in the testing invitation in the TestFlight app. It is recommended to specify key changes, fixed bugs, and new features in each build.

Integrating Pilot into a CI/CD Pipeline

Pilot in CI/CD is the final stage of the iOS app delivery pipeline. After Gym has built the IPA and tests have passed, Pilot uploads the build to TestFlight and distributes it to tester groups. This allows QA teams to get the new app version within minutes after a commit to the repository.

A typical iOS CI/CD pipeline includes the sequence: Match (certificates), Gym (IPA build), Pilot (upload to TestFlight and distribution). Each stage depends on the previous one, ensuring that only valid and signed builds are delivered to testers.

# Full pipeline in Fastfile
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

The skip_waiting parameter in the upload command allows not waiting for Apple’s binary file processing completion within a CI task — Pilot sends an upload request, receives the build identifier, and completes. This speeds up the pipeline since processing can take up to 30 minutes, which are not spent waiting in the CI runner.

For Pilot to work correctly in CI, you need to configure the App Store Connect API key. Save the .p8 key file in the CI system’s secure storage and pass the path via the APP_STORE_CONNECT_API_KEY_PATH environment variable. Pilot uses this key to authenticate in the API without two-factor authentication, which is critical for automated scenarios.

Common Problems When Working with Pilot

When using Pilot, developers most often encounter authentication errors, incorrect app configuration, and issues with binary file processing on Apple’s side. Pilot problem diagnosis starts with checking the build status in App Store Connect via the pilot builds command.

The error “Your app is not available for testing in TestFlight” occurs when the app is not configured for testing in App Store Connect. Solution: open the TestFlight section in App Store Connect, activate testing for the app, and make sure Export Compliance is filled in correctly for your encryption type.

The error “Missing iOS Distribution signing identity” indicates the absence of a Distribution certificate in Keychain. Solution: run Match to download the correct certificate before calling Pilot. A Distribution certificate differs from Development — it is used to sign builds intended for distribution via TestFlight or the App Store.

With the “Invalid Provisioning Profile” error, the build contains an incorrect profile for the selected export method. Solution: check that Gym uses the correct export_method matching the profile type in Match. If the build was built with a development profile, Pilot will not be able to upload it to TestFlight — an app-store or ad-hoc profile is required.