Automating iOS app distribution for QA and reviewers using Bitrise addresses a common pain point—manually sharing builds—by streamlining the process through CI/CD. Bitrise simplifies generating signed IPAs (for ad-hoc testing), uploading to TestFlight, and deploying to third-party services like Firebase App Distribution, all while handling code signing, versioning, and notifications automatically.
This post is a step-by-step guide to help developers set up Bitrise to generate an iOS build artifact for distribution to QA or any reviewer.
Getting in context
To develop this post, we need the app for internal distribution, an iOS Developer Program license from Apple, and a free Bitrise account.
The app we will distribute internally is an iOS project called SMOC. SMOC is a head-up display speedometer and dash camera. The app builds without issues, and all unit tests pass. While this may seem obvious, it’s important to ensure that build crashes do not occur during workflow executions.
Being a member of the Apple Developer Program is mandatory because, at some point during the Bitrise setup, you will need to connect to the Apple Developer portal with your credentials. Additionally, you will need to provide an API key (.p8 file) to Bitrise, generated in the Apple Developer portal and also the Development Certificate (.p12 file).
Bitrise offers a 30-day free trial account that allows you to experiment with and initiate iOS app internal distribution.
Generating Apple Developer API Keys
Login in into your Apple developer account:
Select User and Access. On the incoming screen, choose Integrations > App Store Connect API from the left-side menu. Under Equipment Keys, click the Add (+) button to create a new key.
Important point: Access must be set to ‘Administrative’; I was not successful with the ‘Developer’ role. Download the API key (.p8 file) to a secure location, as we will need it to configure Bitrise. The ID Key and Issuer ID have been masked for security reasons, but make sure to take note of them because you will need them later.
In addition to the API key (.p8 file), we also need the Apple Development Certificate (.p12 file). To obtain it, open Keychain and export the certificate. Remember the password you set during the export process, as it will be required when importing the certificate into Bitrise.
If the certificate is not in your keychain, you can create it via Xcode. Go to Settings > Accounts > Manage Certificates, and select Apple Development. The certificate will automatically be added to your local machine’s keychain and uploaded to the Apple Developer Portal.
General iOS Setup
Once logged into your Bitrise account, the first step—before configuring any project—is to set up some global Bitrise configurations that will be needed later. Since our codebase is hosted on GitHub, we will connect our GitHub account.
Now it’s time to add your API key. Go back to the previous screen, select ‘App Store Connect,’ and press the ‘Add API Key’ button.
The name is an identifier of your choice, but the Issuer ID and Key ID are obtained when you create an API key on the Apple Developer portal. Finally:
Following the ‘least privilege principle’, I initially created an API key with a Developer role. However, the workflow execution failed due to insufficient access rights, so I had to generate a new API key, this time with an Administrator role.
Lastly, we need to connect the Bitrise account with our Apple Developer account, just as we did with GitHub. However, this time, we need to go to the top-right user icon menu.
And connect with your Apple Developer (or Enterprise) account:
iOS Project setup
Now is the time to create a new project. Select the dashboard and click the ‘(+) New Project’ button.
Select ‘Add your App’:
Select ‘New project’:
And press Next.
Fill in the app title, mobile platform, and app bundle ID. Then, select ‘Integrations’ from the left menu.
And just indicate which API key you are going to use.
Go to the Dashboard and select ‘Configure’ in the project you’re working on.
Set up the project and access. In our case, we aim to provide CI builds to team members who either do not have access to Bitrise or are not permitted to use it.
In our case, the code repository is GitHub, so we set the URL to point to our repository.
Bitrise authorization is not strictly necessary because the repository is public. However, if it were private, we would need to authorize access. For the «Choose Branch» step, we select «No, skip auto-detection and configure settings manually» because, although the default branch is develop, developers often distribute builds to their QA colleagues based on their working branches rather than the default branch.
In the ‘Default configuration’, we set the project type, project (or workspace) filename, scheme, and distribution method. In our case, we are interested in distributing builds based on development to our QA team.
Next, we select the XCode version to be used as the toolchain and build machine. Due to our account subscription, we are limited to working with only one type of machine.
Set the app icon to add an avatar to the project, then select ‘Register a Webhook’ for me!
Configuration finished just press ‘View CI configuration’.
Configuration is almost complete, but not quite. Next, we need to upload the Development Certificate (.p12 file). To do this, select ‘Code Signing’ and then click ‘Add .p12 File.
Once added:
Even though we set the API key previously, I faced some compilation crashes that failed due to the API key, so I had to specify again which API key I was going to use.
Project configuration is ready. Now, select workflows to create our workflow, which is also known as pipelines in other contexts.
Workflow creation
On workflows select ‘(+) Create Workflow’:
Fill in the name of the workflow, as well as the workflow on which it is based. In our case, it is ‘archive_and_export_app’:
This would be ok in case our project used Cocoapods as a dependency manager, but is our case is not.
So we have to remove Cocoapods step:
Save workflow:
Workflow execution
Setup work finished, now is time to run the workflow, press ‘Start build’ button:
Press ‘Start build’:
After a few minutes….
If everything is set up correctly, the ‘Success’ message should appear. Now, press the ‘Right arrow’ icon to continue with the build distribution.
Install and run
We need to provide the app download URL, either by distributing a QR code or sharing the direct link. Our responsibilities as developers are complete.
As a QA reviewer, once we scan the QR code or enter the link in the device browser, we will see the following. The setup process will only occur the first time the app is installed. Subsequent re-installations (or removal and reinstallation) will not trigger the setup process again.
Select ‘Check compatibility’ and following alert will appear:
Select Allow for installing configutation profile. And Open Device Settings, General:
Select Allow for installing configutation profile. And Open Device Settings, General, VPN & Device Management:
And select ‘Install’. Remember this setup has to be done once per device and app distributed.
And yes, finally press install to begin installing the app on your device. The following animation will show you how the app is installed and execute:
Conclusions
Although the configuration process can be tedious, once it’s set up, the developer only needs to focus on executing the workflow on the desired working branch and providing the workflow or artifact distribution link to QA or any other interested reviewer. On the QA side, they simply need to click the link to install the app and start testing.