Best practices for distributing Apple apps to QA testers using CI/CD and fastlane

This document introduces best practices for using Firebase App Distribution and fastlane to make your Apple platform pre-release testing workflows sustainable and repeatable in a CI/CD environment. While this document focuses on fastlane, we also describe solutions available through the Firebase console, the Firebase CLI, and the public Firebase App Distribution API to give you more flexibility. We also describe release and tester limits so you can plan in advance for an optimal experience.

If you're also using Android, see Best practices for distributing Android apps to QA testers using CI/CD.

Before you begin

Before you implement the best practices in this document, be sure to enable App Distribution in the Firebase console for each app. If you haven't enabled App Distribution, you'll get a 404 error.

To enable App Distribution, follow these steps:

  1. Open the App Distribution page in the Firebase console.

  2. Select your iOS app.

  3. Click Get Started.

Automate your pre-release testing workflow using CI/CD

If you want to automate building and releasing apps to your testers and you're using CI/CD, we recommend that you use fastlane. Another option is to use the Firebase CLI, which lets you access a wide array of Firebase products.

Use fastlane

Integrate App Distribution into your CI/CD pipeline using fastlane, an open source tool that automates building and releasing iOS and Android apps. By building and distributing your latest releases to testers automatically, you ensure testers always have the most up-to-date test version of your app.

To learn how to integrate App Distribution with fastlane, see Distribute iOS apps to testers using fastlane. See also a codelab that walks you through the fastlane integration process.

Use the Firebase CLI

Use the Firebase CLI tools that App Distribution provides to distribute builds to testers programmatically. You can specify testers and release notes for a build.

Distribute your latest iOS build test.ipa by specifying the app’s Firebase App ID, optionally adding a release note and a file containing testers’ emails:

firebase appdistribution:distribute test.ipa  \
    --app 1:1234567890:ios:0a1b2c3d4e5f67890  \
    --release-notes "Bug fixes and improvements" --testers-file testers.txt

To learn more about using the Firebase CLI to automate your builds, see Distribute iOS apps to testers using the Firebase CLI.

Use service credentials to authenticate

Use the App Distribution fastlane plugin or the Firebase CLI with service accounts, which take advantage of Application Default Credentials and help you manage your CI. A service account is a type of Google account that represents applications as opposed to users. Your CI system can use service accounts to run your App Distribution workloads. To learn more, see Authenticate with a service account.

If you're using workload identity federation, you can generate and use a credential configuration file instead of a service account key.

Keep in mind release limits

App Distribution supports a maximum of 1,000 releases per app. This means that when you exceed the release limit, App Distribution automatically deletes the oldest releases above the limit. To learn how to manage release limits, see How long are app releases available?

Add the same set of testers to multiple releases

If you want to add large numbers of testers to your releases, use App Distribution's bulk tester management functionality.

We recommend that you use groups to add the same testers to multiple releases. A group acts as an access control list; when you remove a tester from a group, they lose access to all of the releases distributed to that group. To learn more, see Add and remove testers from a group.

If you have a lot of testers to manage, you can bulk add and delete testers using the Firebase console. To automate adding and removing testers, use the Firebase CLI, fastlane, or the public Firebase App Distribution API.

Keep in mind tester limits

App Distribution limits the number of testers you can add to a Firebase project or an App Distribution group. When you exceed these limits, you won't be able to distribute your app to additional testers. To learn more about tester limits, see Are there limits for adding testers to my app?

Manage and automatically add new iOS tester devices

To help you register additional iOS tester devices, App Distribution helps you manage your iOS tester devices in the Apple Developer Portal by informing you about new tester iOS devices via email or CSV files. To learn more, see Import testers from CSV files. You can also programmatically export new devices using fastlane.

To learn how to set up a fastlane action that automatically pulls down UDIDs, adds them to the Apple developer console, and then rebuilds the app and distributes it, see Distribute your pre-release iOS builds faster with App Distribution and fastlane.

Enable potential testers to self-register for testing

To make it easier to distribute your app to more testers, we recommend that you use invite links. An invite link is a unique URL that lets testers enter their email addresses to sign up to test an app. Enabling users to add themselves to your list of app testers is a seamless way to increase your internal testing base.

Invite links use cases include company dogfood programs, organizations with large QA teams, and developer groups who want individual clients to be able to control tester access.

We recommend that you create an invite link for a group. Any tester who signs up using the invite link is automatically added to subsequent releases.

To learn more, see Create invite links and Add and remove testers from a group.

Make sure that testers are testing the version you care about

When a new version is uploaded, your testers are notified by email. To supplement this notification, you can use the following features – release links and in-app alerts – to make sure that your testers are testing the specific app version you care about:

  • Release links: Use this feature when you want to share a specific version with testers. To learn how to use release links, see Distribute iOS apps to testers using the Firebase console. These links are also available with our Firebase and fastlane command-line (CLI) tools for use with your build automation tools.

  • In-app alerts: Use these alerts when you want to ensure that your testers are testing the latest version of your app. By integrating the Firebase App Distribution iOS SDK, you can display alerts directly inside the app to your testers when new builds of your app are available. To learn how to add in-app alerts, see Notify testers about new builds.

Automatically remove access for testers who leave the company

Once your CI/CD internal testing flow is up and running, you need to make sure that people who leave the company no longer have access to your internal builds. To help you manage tester access to builds, App Distribution provides the following options: