Distribute iOS Builds with TestFlight

Welcome to the first lesson of our final module on app submission. In the previous module, we meticulously prepared our app for the stores by configuring records in App Store Connect and Google Play Console, and by completing the necessary privacy declarations. With all that preparatory work done, we can now shift our focus from metadata to the actual application binary.

This lesson marks a significant milestone: moving your app from your local development environment into Apple's ecosystem for testing. We will cover the complete process of uploading your archived iOS build to App Store Connect and distributing it to your first set of testers. We'll specifically focus on internal testing—a crucial first step where you share the app with a small, trusted group of team members before a wider release.

1. The Pre-Upload Checklist: Versioning and Building

Before creating the official build for distribution, there are two critical housekeeping tasks: updating your web assets and setting the app's version numbers.

In your Turborepo setup, you'll first run your web app's build script to generate the latest production-ready assets. Then, you'll sync these assets into your native iOS project.

# 1. Build the React web app
bun run build




# 2. Sync the web assets and native dependencies
bunx cap sync ios

Next, you need to manage the Version and Build numbers in Xcode. These are found in the "General" tab of your app's target settings.

• Version (Marketing Version): This is the public-facing version number, like 1.0.0, 1.1, etc. It follows semantic versioning principles. A change here will require a new, albeit lightweight, review from Apple even for TestFlight distribution to external testers.
• Build: This is an internal, incremental number (e.g., 1, 2, 3). You must increment this number for every single build you upload to App Store Connect. Uploading a build with a number that already exists will result in an error. For internal testing, you can increment the build number without changing the version number to push quick updates without triggering a review.

The video below from Sean Allen provides an excellent explanation of this versioning strategy and its implications for the review process.

2. Archiving the Build in Xcode

With your web assets synced and version numbers set, you are ready to "archive" the app. An archive is a special type of build package that contains your compiled app and its symbols, prepared for distribution.

1. Open the project:

   bunx cap open ios
   

2. Select the Build Target: In the toolbar at the top of Xcode, change the run destination from a specific simulator (e.g., "iPhone 15 Pro") to Any iOS Device (arm64). The "Archive" option will be grayed out if a simulator is selected.
3. Create the Archive: From the top menu bar, select Product → Archive. Xcode will now compile and bundle your application. This can take a few minutes, especially the first time.

Once the process is complete, Xcode's Organizer window will open, displaying your newly created archive.

The following Ionic blog post provides a clear, step-by-step guide with screenshots that mirrors this process.

3. Uploading to App Store Connect

From the Organizer window, the final upload process begins.

1. With your new archive selected, click the blue Distribute App button on the right.
2. A dialog will appear. Follow these steps:
   • Method: Select App Store Connect. This is the destination for all builds intended for TestFlight or the public App Store.
   • Destination: Select Upload. This sends the archive directly to Apple's servers.
   • Distribution options: Keep both checkboxes selected:
     • Upload your app's symbols...: This is crucial for receiving human-readable crash reports.
     • Include bitcode for iOS content: This allows Apple to re-optimize your app for future devices without you needing to submit a new build.
   • Signing: Xcode will summarize the provisioning profile and certificate it will use. If you have "Automatically manage signing" enabled, this should be seamless. It will locate or generate the necessary distribution certificate.

After confirming the summary, Xcode will validate the archive and begin uploading it. This final step involves communicating with App Store Connect and pushing the binary to Apple's servers.

The video from Sean Allen is invaluable here as he encounters and solves a common real-world issue—a missing app icon—which demonstrates the kind of validation that happens at this stage.

4. Distributing to Internal Testers via TestFlight

Once the upload is successful, you can close Xcode. The rest of the process takes place in the App Store Connect web portal.

Build Processing and Compliance

Navigate to your app in App Store Connect and click the TestFlight tab. You should see your new build with a "Processing" status. Apple performs automated checks on the build, which can take anywhere from a few minutes to an hour or more. You will receive an email when it's done.

Once processing is complete, you'll likely see a yellow warning for "Missing Compliance." This relates to export laws for encryption.

• Click Manage next to the warning.
• You'll be asked if your app uses encryption. Since your app makes HTTPS calls and uses standard system-level encryption, you should select Yes.
• This will satisfy the compliance requirement for TestFlight distribution.

Setting Up an Internal Testing Group

TestFlight distinguishes between two types of testers:

• Internal Testers: Up to 100 users who have a role (like Admin, Developer, or App Manager) in your App Store Connect account. Builds for internal testers are available immediately without a review.
• External Testers: Up to 10,000 users invited via email or a public link. Their first build requires a lightweight review from Apple.

We will focus on internal testers. The official Apple documentation provides a clear, step-by-step guide.

To summarize the process you just read about:

1. In the TestFlight tab, click the + button next to "Internal Testing" in the sidebar to create a group (e.g., "Core Dev Team").
2. Click on the newly created group, then select the "Testers" tab and invite the App Store Connect users you want to test the build. They will receive an email invitation.
3. Select the "Builds" tab for that group and click the + icon to add your newly processed build. You can add notes under "What to Test" to guide your testers.

Once the build is added, your invited testers can open the TestFlight app on their iPhones, accept the invitation, and install your application.

The following video provides a concise visual walkthrough of creating groups and distributing the build within the App Store Connect UI.

Conclusion

Congratulations! You have successfully navigated the path from a local build to a distributable app within Apple's testing framework. This process, while multi-faceted, becomes routine with practice.

Here are the key takeaways from this lesson:

• The Upload Workflow: The core process is to build and sync your web assets, Archive from Xcode using the "Any iOS Device" target, and then Distribute App to App Store Connect via the Organizer.
• Versioning is Critical: Always increment your Build number for each upload. Only change the Version number for significant updates.
• Post-Upload Processing: After uploading, builds must be processed by Apple and may require you to answer encryption compliance questions before they can be tested.
• Internal Testing is the First Step: Internal testing is a fast, review-free way to get your app into the hands of your immediate team members by leveraging their App Store Connect user accounts.

In our next lesson, we will expand our testing circle. We will explore how to manage TestFlight builds further and invite external testers, which involves a public link and Apple's beta app review process.