fastlane/lib/fastlane/actions/docs/upload_to_testflight
The best way to manage your TestFlight testers and builds from your terminal
pilot makes it easier to manage your app on Apple’s TestFlight. You can:
- Upload & distribute builds
- Add & remove testers
- Retrieve information about testers & devices
- Import/export all available testers
pilot uses spaceship.airforce to interact with App Store Connect 🚀
pilot is part of fastlane: The easiest way to automate beta deployments and releases for your iOS and Android apps.
Usage
For all commands, you can either use an API Key or your Apple ID.
App Store Connect API Key
The App Store Connect API Key is the preferred authentication method (if you are able to use it).
- Uses official App Store Connect API
- No need for 2FA
- Better performance over Apple ID
Specify the API key using --api_key_path ./path/to/api_key_info.json or --api_key "{\"key_id\": \"D83848D23\", \"issuer_id\": \"227b0bbf-ada8-458c-9d62-3d8022b7d07f\", \"key_filepath\": \"D83848D23.p8\"}"
Go to Using App Store Connect API for information on obtaining an API key, the fastlane api_key_info.json format, and other API key usage.
Apple ID
Specify the Apple ID to use using -u felix@krausefx.com. If you execute pilot in a project already using fastlane the username and app identifier will automatically be determined.
Uploading builds
To upload a new build, just run
fastlane pilot upload
This will automatically look for an ipa in your current directory and tries to fetch the login credentials from your fastlane setup.
You’ll be asked for any missing information. Additionally, you can pass all kinds of parameters:
fastlane action pilot
You can pass a changelog using
fastlane pilot upload --changelog "Something that is new here"
You can also skip the submission of the binary, which means, the ipa file will only be uploaded and not distributed to testers:
fastlane pilot upload --skip_submission
pilot does all kinds of magic for you:
- Automatically detects the bundle identifier from your
ipafile - Automatically fetch the AppID of your app based on the bundle identifier
pilot uses spaceship to submit the build metadata and the iTunes Transporter to upload the binary. Because iTunes Transporter’s upload capability is only supported on OS X, pilot upload does not work on Linux, as described in this issue
List builds
To list all builds for specific application use
fastlane pilot builds
The result lists all active builds and processing builds:
+-----------+---------+----------+ | Great App Builds | +-----------+---------+----------+ | Version # | Build # | Installs | +-----------+---------+----------+ | 0.9.13 | 1 | 0 | | 0.9.13 | 2 | 0 | | 0.9.20 | 3 | 0 | | 0.9.20 | 4 | 3 | +-----------+---------+----------+
Managing beta testers
List of Testers
This command will list all your testers, both internal and external.
fastlane pilot list
The output will look like this:
+--------+--------+--------------------------+-----------+ | Internal Testers | +--------+--------+--------------------------+-----------+ | First | Last | Email | # Devices | +--------+--------+--------------------------+-----------+ | Felix | Krause | felix@krausefx.com | 2 | +--------+--------+--------------------------+-----------+ +-----------+---------+----------------------------+-----------+ | External Testers | +-----------+---------+----------------------------+-----------+ | First | Last | Email | # Devices | +-----------+---------+----------------------------+-----------+ | Max | Manfred | email@email.com | 0 | | Detlef | Müller | detlef@krausefx.com | 1 | +-----------+---------+----------------------------+-----------+
Add a new tester
To add a new tester to your App Store Connect account and to associate it to at least one testing group of your app, use the pilot add command. This will create a new tester (if necessary) or add an existing tester to the app to test.
fastlane pilot add email@invite.com -g group-1,group-2
Additionally you can specify the app identifier (if necessary):
fastlane pilot add email@email.com -a com.krausefx.app -g group-1,group-2
Find a tester
To find a specific tester use
fastlane pilot find felix@krausefx.com
The resulting output will look like this:
+---------------------+---------------------+ | felix@krausefx.com | +---------------------+---------------------+ | First name | Felix | | Last name | Krause | | Email | felix@krausefx.com | | Latest Version | 0.9.14 (23 | | Latest Install Date | 03/28/15 19:00 | | 2 Devices | • iPhone 6, iOS 8.3 | | | • iPhone 5, iOS 7.0 | +---------------------+---------------------+
Remove a tester
This command will remove beta tester from app (from all internal and external groups)
fastlane pilot remove felix@krausefx.com
You can also use groups option to remove the tester from the groups specified:
fastlane pilot remove felix@krausefx.com -g group-1,group-2
Export testers
To export all external testers to a CSV file. Useful if you need to import tester info to another system or a new account.
fastlane pilot export
Import testers
Add external testers from a CSV file. Create a file (ex: testers.csv) and fill it with the following format:
John,Appleseed,appleseed_john@mac.com,group-1;group-2
fastlane pilot import
You can also specify the directory using
fastlane pilot export -c ~/Desktop/testers.csv fastlane pilot import -c ~/Desktop/testers.csv
Tips
Debug information
If you run into any issues you can use the verbose mode to get a more detailed output:
fastlane pilot upload --verbose
Firewall Issues
pilot uses the iTunes Transporter to upload metadata and binaries. In case you are behind a firewall, you can specify a different transporter protocol from the command line using
DELIVER_ITMSTRANSPORTER_ADDITIONAL_UPLOAD_PARAMETERS="-t DAV" pilot ...
If you are using pilot via the fastlane action, add the following to your Fastfile
ENV["DELIVER_ITMSTRANSPORTER_ADDITIONAL_UPLOAD_PARAMETERS"] = "-t DAV" pilot...
Note, however, that Apple recommends you don’t specify the -t transport and instead allow Transporter to use automatic transport discovery to determine the best transport mode for your packages. For this reason, if the t option is passed, we will raise a warning.
Also note that -t is not the only additional parameter that can be used. The string specified in the DELIVER_ITMSTRANSPORTER_ADDITIONAL_UPLOAD_PARAMETERS environment variable will be forwarded to Transporter. For all the available options, check Apple’s Transporter User Guide.
Credentials Issues
If your password contains special characters, pilot may throw a confusing error saying your “Your Apple ID or password was entered incorrectly”. The easiest way to fix this error is to change your password to something that does not contains special characters.
How is my password stored?
pilot uses the CredentialsManager from fastlane.
Provider Short Name
If you are on multiple App Store Connect teams, iTunes Transporter may need a provider short name to know where to upload your binary. pilot will try to use the long name of the selected team to detect the provider short name. To override the detected value with an explicit one, use the itc_provider option.
Use an Application Specific Password to upload
pilot/upload_to_testflight can use an Application Specific Password via the FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD environment variable to upload a binary if both the skip_waiting_for_build_processing and apple_id options are set. (If any of those are not set, it will use the normal Apple login process that might require 2FA authentication.)
Role for App Store Connect User
pilot/upload_to_testflight updates build information and testers after the build has finished processing. App Store Connect requires the “App Manager” or “Admin” role for your Apple account to update this information. The “Developer” role will allow builds to be uploaded but will not allow updating of build information and testers.