Getting started with iOS apps

Abstract

Get started on Bitrise by signing up via email or a Git provider, connecting a repository, and running the first build for your iOS app.

Developing for iOS is not always easy - our aim is to make it as simple as possible for you! In this guide, we’ll walk you through how to add an iOS app to Bitrise, how to run Xcode tests, manage your code signing files, and deploy the app to bitrise.io and to the App Store.

Integrating fastlane to Bitrise

You can run your fastlane lane on Bitrise with the same commands you would use locally. Bitrise’s automated Steps provide extra functionality to your lane and speed up your builds. For more information, check out Integrating fastlane to Bitrise.

Adding an iOS app to Bitrise

Do you have a Bitrise account?

Make sure you have signed up to bitrise.io and can access your Bitrise account. There are multiple ways of registering an account:

Go to your Bitrise Dashboard.
Click the + sign on the top menu bar and select Add New App on web UI, which takes you to the Create New App page.

Alternatively, you can add your app using a CLI. For more details, check out Adding a new app from a CLI.
Choose the account you wish to add the app to.
Set the privacy of the app to either Private or Public and click Next.

Private vs public apps

The most important difference between public and private apps is that if your app is public, everyone who has the build URL can see your build logs: Public apps. With a private app, you have full control over who has any access to the app.
Select the Git hosting service that hosts your repository, then find and select your own repository that hosts the project.
When prompted to set up repository access, click No, auto-add SSH key.
Type the name of the branch that includes your project’s configuration - main, for example, - then click Next.
Wait while Bitrise is validating your project.

We look for your configuration files and set up your app based on them. In the case of an iOS app, we’re looking for your Xcode Project (.xcodeproj) or Xcode Workspace (.xcworkspace) path. Note that the validation will fail if you do not have a SHARED scheme in your project. You can still point Bitrise manually to your Xcode scheme but if it’s shared, we automatically detect it for you.
Select the IPA export method. You can modify this later - for now, select development.

Once you clicked it, you should see your:
- Project or Workspace path.
- Scheme name
- IPA export method.
- iOS stack.
Register a webhook when prompted so that Bitrise can start a build automatically when code is pushed to your repository, or a pull request is created. This also kicks off your first build - click the message and it will take you to the build page.

Testing your iOS app

Once you created your app, the first build will run based on the automatically created primary workflow. You can check it out in the app’s Workflow Editor: click the app’s name on your Dashboard then click the Workflow tab.

If you have test targets defined, the primary workflow of an iOS app includes the two Steps you need to run your Xcode tests, and view their results on bitrise.io:

Xcode Test for iOS
Deploy to Bitrise.io

Code signing files

Running Xcode tests and deploying their results to Bitrise do not require any code signing files. So don’t worry about them just yet!

The Xcode Test for iOS Step runs the pre-defined Xcode tests. It has a default configuration that does not need to be modified: if the tests are written correctly, they will work. You can find the same configuration options in Xcode, too.

Checking your selected stack in the Stacks & Machines tab

We recommend checking that the stack selected for your app has the same Xcode version you used to build the app. For example, if your simulator test fails with the Ineligible destinations for the scheme message, then make sure the Xcode version in the Stacks & Machines tab is correct. You can read more about our stacks: Build stacks.

The Deploy to Bitrise.io Step will deploy the following to the Logs and Artifacts tab of the build:

Your Xcode test results.
Your raw xcodebuildoutput log.

The Deploy to Bitrise.io Step also exports the results of the Xcode Test for iOS Step to the Test Reports add-on.

Creating a signed IPA for Xcode projects

Abstract

You can easily create a signed IPA file for your Xcode project with Bitrise if you have your Apple connection set up correctly and you made code signing files available to your builds.

Overview on iOS code signing in Bitrise

For a comprehensive overview on what Steps are available for code signing asset management, visit the iOS code signing page.

You can easily create a signed IPA file for your Xcode project with Bitrise.

You have set up Apple service connection on Bitrise.
Your code signing files are managed correctly.
You set the relevant inputs of our Xcode Archive and Export for iOS Step.

Upload the distribution AND the development signing certificates

We strongly recommend uploading BOTH the development and distribution signing certificates for your project. If you don't have an uploaded development signing certificate, Steps with automatic provisioning options will generate one on the fly every time you start a build. This can eventually lead to reaching the maximum number of certificates, blocking you from starting new builds.

If you’re all set, proceed to setting up IPA export in your Workflow.

Make sure the necessary code signing files have been collected and uploaded.
Make sure you have the Xcode Archive & Export for iOS Step in your Workflow.
Set the Distribution method input of the Step.

The options are:
- auto-detect - Please note that this option is deprecated and will be removed. We do not recommend using it.
- app-store: Choose this if you want to deploy the app to the App Store. Requires a Distribution certificate and an App Store provisioning profile.
- ad-hoc: Choose this if you want to deploy the app to ad-hoc testers. Requires a Distribution certificate and an Ad Hoc provisioning profile.
- enterprise: Choose this if you have an Apple Enterprise account and want to use that to distribute your app.
- development: Choose this for internal testing. Requires a Developer certificate and a Development provisioning profile.
Set the Automatic code signing input to the Apple service connection you want to use for code signing. The available options are:
- off if you don’t do automatic code signing.
- api-key if you use API key authorization.
- apple-id if you use Apple ID authorization.
Save the Workflow, and start a new build.

That’s all. Xcode will automatically select the right signing files based on your project’s Bundle ID and Team ID settings, and the export method you set.

Signing an IPA file with a different team’s code signing file

You might want to sign the IPA file with a different team’s code signing files. For example:

If you use your company’s code signing files for internal builds, but your client’s code signing files are used for App Store distribution.
If you use Apple ID for automatic code signing and the Apple ID belongs to multiple teams, use The Developer Portal team to use for this export input to specify which team should be used for automatic code signing asset management.

To do so:

Make sure the right code signing files of the new development team are uploaded to Bitrise.
Set the The Developer Portal team to use for this export option as well (in addition to the Distribution method).
Set the Distribution method.

Deploying the app to App Store Connect

Keep in mind that every time you want to push an app to App Store Connect, it must have a unique build and version number: increment either or both before deploying.

Make sure you have a working connection to your Apple Developer account.
Generate an IPA file on your own machine at least once.
Upload all necessary code signing files to Bitrise.

To deploy an app to App Store Connect, you need a Distribution type certificate and an App Store type provisioning profile.
Make sure the Xcode Archive & Export for iOS Step is in your Workflow.
Set the Automatic code signing input to the Apple service connection you want to use for code signing. The available options are:
- off if you don’t use automatic code signing, or if you exclusively use Step inputs for Apple service authentication.
- api-key if you use API key authorization.
- apple-id if you use Apple ID authorization.
Set the Distribution method input of the Step to app-store.

The Step will store the path of the exported .ipa file in the $BITRISE_IPA_PATH Environment Variable.
Add the Deploy to App Store Connect Step to your Workflow.
Fill the required inputs.
- Either the app’s Apple ID or its Bundle ID is a required input. One of the two must be provided.
- If you set the Submit for Review to true, the Step will wait for your submission to be processed on App Store Connect and then submit the given version of the app for review.
- The default value of the Skip App Version Update input is No. Change it only if you incremented the app version number in another way.
- If you use an App Store Connect account that is linked to multiple teams, provide either a Team ID or a Team name!
Start a build.

If all goes well, your app will be submitted to App Store and you can distribute it via Testflight or via the App Store!

In this section: