Installing an .ipa file

Abstract

You can install .ipa files either from the public install page or from the Artifacts tab of your build.

Both the public install page and accessing the .ipa file from the Artifacts tab enables you to install .ipa files on provisioned and registered test devices. The allowed device types are: iPhone and iPad.

Installing an .ipa file on a test device consist of three phases: initiating the device compatibility check, installing a configuration profile on the test device, then finishing up with installing the app on the device.

In this tutorial we’re describing:

How to install an app on a registered test device without a Bitrise account (for anyone who has not subscribed to Bitrise but wishes to check out the current version of the app).
How to install an app on a test device which is yet to be registered on Bitrise (for Bitrise users).

Installing an .ipa file from the Artifacts tab

Installing an .ipa file from the Artifacts tab is only possible for Bitrise users.

Prepping for installation

Before installing the app on any test device, the app’s developer has to complete a couple of steps to build the app and share it with anyone:

The device, on which the app will be installed, is registered as a test device at the developer’s Apple account.
The device has to be included in the provisioning profile of the app.
The device meets the minimum OS requirements of the app.

Please note that if the test device is not registered on the Apple Developer portal, the developer has to manually add it to the device list, and re-build the app so that the .ipa file contains the test device/s the app can be installed on. We also recommend you register the test device on Bitrise as well.

Which browser should I use with the public install page?

Anyone who wishes to install the app on a test device has to make sure that the public install page of the app is opened in a native Safari session with non-incognito mode.

Installing an .ipa file from Bitrise's public install page to an iPad with iPadOS

If you are using an iPad running iPadOS, make sure that you open the Bitrise public install page in mobile mode.

When you open the public install page of an .ipa file, Bitrise checks if the device is stored in the embedded provisioning profile or not. This check can only complete if you visit the public install page in mobile mode instead of the desktop version. We suggest that you switch to mobile mode temporarily.

You can easily switch to mobile mode temporarily if you tap the ᴀA icon on the left corner of the Safari address bar and then tap the Show Mobile Website option.

Installing an .ipa file on test devices from the public install page

The public install page is a convenient way of sharing the latest version of your app with team members and any other stakeholders who wish to check the app out. The page includes all the important details of the build such as filename, size, version code, minimum SDK version, and build number. Anyone, whose email address or Bitrise team role you add before building the app, will receive an email from Bitrise with a link to the public install page. The public install page’s direct link can be shared with anyone as well. From there they can quickly install the app on their own test device.

During this whole flow, use a native, non-incognito Safari session instead of any other in-app browser type. If you follow the link in the notification email you got from Bitrise, the public install page will automatically open in a native Safari session.

Would you rather download the app?

If you only wish to download the app and manually upload it somewhere else, you can find the download button on the Artifacts page of the build. Please note that downloading an app does not mean you can install it on the test device.

Installing an app on a test device without a Bitrise account

Long tap on the link you received from Bitrise. To open the link in native Safari, tap Open Link. It brings up the public install page in a native Safari session. If you copy the link from the email, make sure you paste it in a native Safari session.
Tap the link in the Click here to check device compatibility of this device with this app yellow message box. If you cannot see this message, you are most likely using another browser so switch to Safari.
Tap Allow on the pop-up to install the configuration profile on your device. This configuration profile makes the device’s UDID available to Bitrise for the compatibility check.
A pop-up confirms the configuration profile has been downloaded, and it can be installed in the Settings app. Tap Close.
Tap the Home button to go the the home screen.
Open Settings. You can find the downloaded profile at the top of the Settings. Tap Profile Downloaded menu item on the left to install the profile.
Tap Install.
Type your device’s passcode in the Enter passcode pop-up.
Tap Install again.
Wait until the profile is installed.
Once the profile is installed, you’re directed to the public install page. As you can see, the Install button is now available. Tap it!
Tap OK on the next pop-up.
As a final confirmation, tap on Install and press the Home button. Now you’re installing the app to your test device.
Wait till the app installs on your test device’s home screen.

Check out the app you’ve successfully installed on your test device.

Installing an app on a test device not registered to Bitrise

If you’re accessing the public install page from a test device which displays the below message, you’ll have to register the device on Bitrise which is only a few steps different from the above flow.

Please note that you can only add a test device to Bitrise if you already have a Bitrise account.

Installing an ipa file from the public install page

Tap Click here to start the device registration process.
Tap Allow to download the configuration profile.
When the configuration profile is downloaded, tap Close.
Tap the Home button to go to your Settings app on your test device’s home screen.
Open Settings. You can find the downloaded profile at the top of the Settings. Tap Profile Downloaded menu item on the left to install the profile.
Tap Install.
Type your device’s passcode in the Enter Passcode pop-up.
Tap Install again in the Install Profile pop-up.
Wait until the profile installation is complete. You automatically get redirected to the Register your test device page.
Your device’s name and UDID gets populated automatically. You can only change the device name here. Tap Register Device.
You land on the public install page where the Install button is now available. Tap it!
Tap OK on the prompt.
To install the app on your test device, tap on Install. Then press the Home button to follow the installment of your app.

If all went well, you can find the installed app on your test device’s Home page.

Installing an .ipa file on test devices from the Artifacts tab

You can install an .ipa file from the Artifacts tab of your app's build. This provides a more secure way compared to the public install page but requires you to log in to your Bitrise account, making it less viable for external testers.

To install an .ipa file from the Artifacts tab:

Open your app on Bitrise.
Select the build with the .ipa file you would like to install.
Go to the Artifacts tab.
Click on Download next to the .ipa file.
Click Install, under the Install the app on your iOS device section.

In this section: