Getting started with iOS projects

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 complex - our aim is to make it as easy as possible for you! In this guide, we’ll walk you through how to add an iOS project to Bitrise, how to run Xcode tests, manage your code signing files, and deploy the finished 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 project 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:

Log in to Bitrise and go to the Dashboard.
Click the New CI project button.
Under Project access, select the Workspace that will own the project.
Set the privacy of the project.

Privacy is final

You cannot change this setting later! If you realize you've accidentally added your project as a public project even though you need it to be private, you'll have to delete the project and add it again.
- Private projects are only accessible to you, your Workspace members and those who are invited to work on a project. They require authentication to access the repository of the project.
- Public projects expose their bitrise.yml and their build logs to everyone. If you have a public project’s build URL, you can view its build log, to help with troubleshooting, for example. Public projects do not require authentication and they cannot have SSH keys.
Select one of two options to set your repository URL:
- With the Select remote repository option, you can select a repository from a list of repos from a connected Git provider account. Choose the Git provider from the dropdown menu, then click Select a repository... and select the repository from the list.
- The Enter URL manually option does not require a connected Git provider account: you can simply enter the URL and proceed to the authentication phase. We strongly recommend using an SSH URL, unless you are setting up a public project.
Repository URL

You will be able to change your project's repository URL later. You can also connect or disconnect your account to Git provider services at any time.

If you signed up for Bitrise using a Git provider account, that one is already connected and you can select any of your repositories from it.
If you use an OAuth connection, you need to add an SSH key in the Authorize Bitrise section.

You don't need SSH keys if:
- Your project is a public project.
- You connect to your Git repository via a GitHub project installation.
- Auto-add a generated SSH key to your repository: We recommend using this option. We automatically generate an SSH key pair and register the public key to your repository. Requires your connected Git provider account to have admin rights to the repository.
- Copy a generated SSH key to your Git provider manually: We generate an SSH key pair for you and you can copy the public key and register it manually to your Git provider. It is useful if, for example, you need to access multiple repositories with the same SSH key.
- Add your own SSH key to Bitrise: You can generate your own SSH key and paste the private key here after choosing this option. You also need to add the public key to the repository manually. To generate your SSH key pair: Generating your own SSH keypair.
Configure SSH keys at any time

If you can't set up a valid, working SSH key connection at this time, don't worry: proceed with adding your project. You can set up the SSH connection afterwards: Configuring SSH keys.
Select the default branch of your repository. This branch should contain the configuration of your project.
- If you successfully configured SSH access in the previous step or if you're adding a public project, Bitrise will parse your repository and allow you to select a branch from a dropdown menu.
- If you didn't configure repository access, you need to type the branch name manually.
You can change the default branch of the project later.
In the next step, choose Yes, auto-detect configuration. Bitrise will scan your repository and attempt to set up a stack and default Workflows based on the results of the scan. In most cases, we recommend choosing this option.

Project type

Detecting a project type serves to assist in the initial configuration of your project. But don't worry, you can change every setting, including the project type, at any time after you added the project.
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.
Once you are done, click View Project Page to go to the newly added project's home page. From there, you can start editing your Workflows and run builds.

Testing your iOS app

If you have test targets defined, the default Workflows of an iOS project include 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

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

We recommend checking that the stack selected for your project has the same Xcode version you used to build the project. 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 section 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.

Workflow Editor

bitrise.yml

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:
- 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 use 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.

Make sure all the necessary code signing files are available for your build.
Open the bitrise.yml file of your app.
Make sure you have the xcode-archive Step in your Workflow.
```
my-workflow:
  steps:
  - xcode-archive:
      inputs:
```
Set the distribution_method input to the correct value. The available options are:
- 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.
```
my-workflow:
  steps:
  - xcode-archive:
      inputs:
      - distribution_method: development
```
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.Connecting to services
- apple-id if you use Apple ID authorization.
```
my-workflow:
  steps:
  - xcode-archive:
      inputs:
      - automatic_code_signing: api-key
      - distribution_method: development
```

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: