Alias for the upload_to_testflight action
- I just uploaded a minor update (0.1.0 to 0.2.0) of my iOS 8 beta app to Apple TestFlight. My app got approved by Apple TestFlight earlier and I read that minor updates don't need another review. Is this still the case? (I'm asking because I needed to submit it for another review even the changes are minimal).
- Just in time for summer: Betaflight 4.2. Just in time for summer for most of us, and in time for the end of COVID-19 related lockdowns in a lot of places, we are proud to announce the release of Betaflight 4.2.0!
- TestFlight, a service allowing developers to beta test mobile apps on the fly, is now available as a native iPhone and iPad application in the App Store. Apple snapped up Burstly, the company behind TestFlight, back in February to help its registered developers distribute their iPhone and iPad apps to beta testers before pushing them to the App.
The best way to manage your TestFlight testers and builds from your terminal
TestFlight will notify you each time a new build is installed on your device. Automatic updates can be turned off at any time. Change automatic update settings for all of the beta apps you’re testing using TestFlight: TestFlight for iOS. Open TestFlight and tap Settings in the upper-right corner. Tap Automatic Updates. Placiibo is opening up TestFlight from version 0.1.0 onwards and is in need of your testing (iOS). I’m on the last iOS beta with iPhone 11 Pro.
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 🚀
Usage • Tips
pilot is part of fastlane: The easiest way to automate beta deployments and releases for your iOS and Android apps.
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 fastlaneapi_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
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:
You can pass a changelog using
You can also skip the submission of the binary, which means, the ipa file will only be uploaded and not distributed to testers:
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
The result lists all active builds and processing builds:
Managing beta testers
List of Testers
This command will list all your testers, both internal and external.
The output will look like this:
Add a new tester
To add a new tester to both your App Store Connect account and to your app (if given), use the pilot add command. This will create a new tester (if necessary) or add an existing tester to the app to test.
Additionally you can specify the app identifier (if necessary):
Find a tester
To find a specific tester use
The resulting output will look like this:
Remove a tester
This command will only remove external beta testers.
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.
Import testers
Add external testers from a CSV file. Create a file (ex: testers.csv) and fill it with the following format:
You can also specify the directory using
Debug information
If you run into any issues you can use the verbose mode to get a more detailed output:
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
If you are using pilot via the fastlane action, add the following to your Fastfile
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.
| testflight | |
|---|---|
| Supported platforms | ios |
| Author | @KrauseFx |
7 Examples
Parameters
| Key | Description | Default |
|---|---|---|
api_key_path | Path to your App Store Connect API Key JSON file (https://docs.fastlane.tools/app-store-connect-api/#using-fastlane-api-key-json-file) | |
api_key | Your App Store Connect API Key information (https://docs.fastlane.tools/app-store-connect-api/#use-return-value-and-pass-in-as-an-option) | |
username | Your Apple ID Username | * |
app_identifier | The bundle identifier of the app to upload or manage testers (optional) | * |
app_platform | The platform to use (optional) | ios |
apple_id | Apple ID property in the App Information section in App Store Connect | * |
ipa | Path to the ipa file to upload | * |
demo_account_required | Do you need a demo account when Apple does review? | |
beta_app_review_info | Beta app review information for contact info and demo account | |
localized_app_info | Localized beta app test info for description, feedback email, marketing url, and privacy policy | |
beta_app_description | Provide the 'Beta App Description' when uploading a new build | |
beta_app_feedback_email | Provide the beta app email when uploading a new build | |
localized_build_info | Localized beta app test info for what's new | |
changelog | Provide the 'What to Test' text when uploading a new build | |
skip_submission | Skip the distributing action of pilot and only upload the ipa file | false |
skip_waiting_for_build_processing | If set to true, the distribute_external option won't work and no build will be distributed to testers. (You might want to use this option if you are using this action on CI and have to pay for 'minutes used' on your CI plan). If set to true and a changelog is provided, it will partially wait for the build to appear on AppStore Connect so the changelog can be set, and skip the remaining processing steps | false |
update_build_info_on_upload | DEPRECATED! Update build info immediately after validation. This is deprecated and will be removed in a future release. App Store Connect no longer supports setting build info until after build processing has completed, which is when build info is updated by default | false |
distribute_only | Distribute a previously uploaded build (equivalent to the fastlane pilot distribute command) | false |
uses_non_exempt_encryption | Provide the 'Uses Non-Exempt Encryption' for export compliance. This is used if there is 'ITSAppUsesNonExemptEncryption' is not set in the Info.plist | false |
distribute_external | Should the build be distributed to external testers? | false |
notify_external_testers | Should notify external testers? (Not setting a value will use App Store Connect's default which is to notify) | |
app_version | The version number of the application build to distribute. If the version number is not specified, then the most recent build uploaded to TestFlight will be distributed. If specified, the most recent build for the version number will be distributed | |
build_number | The build number of the application build to distribute. If the build number is not specified, the most recent build is distributed | |
expire_previous_builds | Should expire previous builds? | false |
first_name | The tester's first name | |
last_name | The tester's last name | |
email | The tester's email | |
testers_file_path | Path to a CSV file of testers | ./testers.csv |
groups | Associate tester to one group or more by group name / group id. E.g. -g 'Team 1','Team 2' | |
team_id | The ID of your App Store Connect team if you're in multiple teams | * |
team_name | The name of your App Store Connect team if you're in multiple teams | * |
dev_portal_team_id | The short ID of your team in the developer portal, if you're in multiple teams. Different from your iTC team ID! | * |
itc_provider | The provider short name to be used with the iTMSTransporter to identify your team. This value will override the automatically detected provider short name. To get provider short name run pathToXcode.app/Contents/Applications/Application Loader.app/Contents/itms/bin/iTMSTransporter -m provider -u 'USERNAME' -p 'PASSWORD' -account_type itunes_connect -v off. The short names of providers should be listed in the second column | |
wait_processing_interval | Interval in seconds to wait for App Store Connect processing | 30 |
wait_for_uploaded_build | DEPRECATED! No longer needed with the transition over to the App Store Connect API - Use version info from uploaded ipa file to determine what build to use for distribution. If set to false, latest processing or any latest build will be used | false |
reject_build_waiting_for_review | Expire previous if it's 'waiting for review' | false |
* = default value is dependent on the user's system
Documentation
To show the documentation in your terminal, run
CLI
It is recommended to add the above action into your Fastfile, however sometimes you might want to run one-offs. To do so, you can run the following command from your terminal
To pass parameters, make use of the : symbol, for example
It's important to note that the CLI supports primitive types like integers, floats, booleans, and strings. Arrays can be passed as a comma delimited string (e.g. param:'1,2,3'). Hashes are not currently supported.
It is recommended to add all fastlane actions you use to your Fastfile.
Source code
This action, just like the rest of fastlane, is fully open source, view the source code on GitHub
TestFlight makes it easy to invite users to test your apps and app clip experiences and collect valuable feedback before releasing your apps on the App Store. You can invite up to 10,000 testers using just their email address or by sharing a public link.
Overview
To take advantage of TestFlight, you’ll need to upload at least one beta build of your app to App Store Connect, and invite testers using their email addresses or by sharing a public link. Testers can get started by accepting your email invitation or following the public link. To install your app and provide feedback, testers will use the TestFlight app for iPhone, iPad, iPod touch, Apple Watch, and Apple TV. Testers can turn on automatic updates in the TestFlight app to ensure they’re always testing the latest available build.
Internal Testers
Add up to 100 members of your team who have been assigned the Account Holder, Admin, App Manager, Developer, or Marketing role to quickly test beta builds as you iterate on your app. Each member can test on up to 30 devices. Internal testers can access all of your beta builds available for testing.
External Testers and Groups
Invite up to 10,000 external testers using their email address or by enabling and sharing a public link, which creates an open invitation for anyone to test your app. Simply create a group of testers and add the builds you’d like them to test. You can also create multiple groups and add different builds to each one, depending on which features you want them to focus on. When you add the first build of your app to a group, the build gets sent to beta app review to make sure it follows the App Store Review Guidelines. Testing can begin once your build is approved.
Using Email to Invite Testers
If you know a tester’s email address, you can email an invitation with a link to install your app and start testing. If you have an existing set of external testers or specific people you’d like to invite to test, email can be an effective way to share beta versions of your app.
Using Public Links to Invite Testers
Public links let you share your app with people outside your development team without email or other contact information. You can share your public link on social media, messaging platforms, email campaigns, and more to expand the visibility of your beta test. If you don’t have an established group of external testers, using public links can be an effective way to increase your app’s reach and grow your test audience.
To enable a public link, go to your app’s TestFlight page, click an existing group, and click Enable Public Link. You can then copy the link and share it outside your organization. When you share your public link, many social media platforms will display your app icon, name, and supported device. To help give potential testers additional context, consider including details about your app and TestFlight. Remember not to localize the name TestFlight or create custom badges to promote your app on TestFlight.
If you’d like, you can limit the number of testers that can use the public link to join the group. Depending on your team’s resources, you may want to start small and increase the limit over time. If the group limit is reached or if you disable your public link, anyone trying to become a tester will see a message that your beta is full or no longer accepting new testers. To ensure a good user experience for potential testers, be thoughtful about where you share your public link and when it may be appropriate to remove your public link.
Test Information
Testflight 1.0 Beta Download
When sharing your app with external testers, you’ll need to let them know what to test and any other important information relevant to testing. Enter these details in your app’s Test Information page in App Store Connect. You should also provide an email address that you monitor so you can receive and respond to feedback that testers provide. Test information is optional when distributing your app to internal testers.
Getting Feedback
With TestFlight 2.3 or later on iOS 13 or later, testers can send feedback directly from your app simply by taking a screenshot. They can also provide additional context about an app crash immediately after it occurs. To view this feedback, go to your app’s TestFlight page in App Store Connect, and click Crashes or Screenshots in the Feedback section. Feedback from testers on tvOS or earlier versions of iOS will be sent to the email address you provide in Test Information.
Supported Apps
TestFlight supports apps for iOS, watchOS, tvOS, and iMessage. Up to 100 apps can be tested at a time, internally or externally, and multiple builds can be tested simultaneously. Builds remain active for 90 days after upload.
TestFlight App
Testflight 1.0 Beta Software
When testers are invited to beta test your app, they are prompted to install the TestFlight app from the App Store on their iPhone, iPad, iPod touch, or Apple TV if they don’t already have it installed. The TestFlight app makes installing betas simple, and you don’t need to keep track of UDIDs or provisioning profiles.
Documentation and Help
Testflight 1.0 Beta Login
For step-by-step instructions on creating groups, inviting testers, and adding builds in TestFlight, read App Store Connect Help or watch the TestFlight video tutorial.