Joseph O'Shea

2024 Updated guide: Make it easy to ship TestFlight builds of your iOS app with fastlane

fastlaneiostestflight

Setting up fastlane

This post covers how to use fastlane to ship beta builds of your iOS app to TestFlight.

This post is intentionally light on details and explanations. Instead, it focuses on taking the simple, direct path to getting your builds running.

If you'd like to learn more about the details behind this guide, I'd suggest reading:

Prerequisites

Fastlane requires:

Please see the fastlane docs for more details.

Install fastlane and configure beta builds

  1. Create a Gemfile with these contents:

    source "https://rubygems.org"

    gem "fastlane"

  2. Install fastlane with bundler

    bundle install

  3. Initialize your fastlane config

    bundle exec fastlane init

  4. When prompted, choose option 2. Automate beta distribution to TestFlight

  5. When prompted, enter your Apple ID and log in.

  6. If you have more than one team, you will be asked to select which to use for this project.

Setup fastlane match for codesigning:

  1. Initialize fastlane match config for codesigning

    bundle exec fastlane match init

  2. Choose git

  3. Create a private git repo and paste the URL into the fastlane prompt

  4. Sync your appstore (production) codesigning

    bundle exec fastlane match appstore

  5. You will be prompted for a passphrase. This is the key to unlock your signing certs and should be kept secret! I highly recommend using a password manager to store this.

  6. Go into xcode, and disable "automatic manage signing". Then select the "match" profile for each of the options (debug and release).

  7. Set up an AuthKey in AppStoreConnect to upload builds

    1. You need an AuthKey to authorize fastlane to upload your builds. First, go here in AppStoreConnect
      • note: this URL is accurate at the time of writing but apple changes these things often. You're looking for somewhere to manage/create "App Store Connect API" keys
    2. Now, create a new key. Give it a sensible name, download it, and save it somewhere secure on your computer. Note: his key is a secret. do not store it in git. I also recommend backing it up to a secure storage such as a password manager, secrets vault, or secrets manager if you have one.
    3. Note all these values to use in your Fastfile (see below):
      1. "Issuer ID" (there is only one for your account, list here) -> this will be issuer_id
      2. Key ID (one per key, also here) -> this will be key_id
      3. The path where you stored the key -> this will be key_filepath

  8. Now update your Fastfile to look like the below example. Replace the fields with your own values:

    1. YourProjectName.xcodeproj -> your xcodeproj file name
    2. key_id -> the Key ID from above
    3. issuer_id -> the issuer ID from above
    4. key_filepath -> where you saved the AuthKey
    5. com.YourProjectIdentifier -> to your bundle ID
    6. YourProjectName.xcworkspace -> your xcworkspace file name
    7. YourProjectSchemeName -> to the scheme for your project (hint: if your xcodeproj is YourProjectName.xcodeproj" then your scheme is most likely YourProjectName unless you changed it. You can find the scheme in xcode)

Copy and paste this snippet into your Fastfile and replace the values as specified above:

default_platform(:ios)

platform :ios do
  desc "Push a new beta build to TestFlight"
  lane :beta do
    increment_build_number(xcodeproj: "YourProjectName.xcodeproj")
    app_store_connect_api_key(
      key_id: "GetThisFromAppStoreConnect",
      issuer_id: "GetThisFromAppStoreConnect",
      key_filepath: "$HOME"/dev/keys/AuthKey_YourKeyFromAppStoreConnect.p8"
    )
    match(
      app_identifier: ["com.YourProjectIdentifier"],
      type: "appstore",
    )
    build_app(workspace: "YourProjectName.xcworkspace", scheme: "YourProjectSchemeName")
    upload_to_testflight(skip_waiting_for_build_processing: true)
  end
end

You are all set! If you get stuck or run into any problems, take a look at the fastlane match docs for help.

Using fastlane

To publish a TestFlight build, run:

bundle exec fastlane beta

The build may take a significant amount of time depending on your app. Building my react native app typically takes 15-30 minutes on my laptop.

Possible errors during setup

["Apple provided the following error info:", "Access Unavailable", "You currently don't have access to this membership resource. To resolve this issue, agree to the latest Program License Agreement in your developer account."]

  1. Go to https://appstoreconnect.apple.com/
  2. Log in with your Apple ID
  3. Accept the new developer agreement
  4. Try again