Getting started with iOS builds

To get your build running on CircleCI, you first need to add your project to CircleCI. Once you’ve done this, GitHub/Bitbucket will start notifying us of changes to your repository so we can perform builds.

By default, we build projects on Linux, so you’ll need to enable macOS for your project. You can do this by going to Project Settings -> Build Environment and enabling the Build OS X Project setting.

Build Environment Settings

Assumptions and prerequisites

For our infererence to test your Xcode project, we check for and validate the presence of:

  • an Xcode workspace/project
  • with at least one shared scheme
  • and that the selected scheme has a test action

If none of these are present, then we will not infer any Xcode related test commands for your project.

Sharing Schemes

If you don’t already have a shared scheme, you can do this in Xcode.

First, open your Xcode workspace or project. Then, use the scheme selector to open the Manage Schemes dialogue.

Xcode Scheme Selector

In the manage schemes dialog, select the scheme you wish to build, and ensure that the Shared checkbox is enabled.

Manage Schemes Dialogue

Finally, commit and push the schemes.


Builds are broken up into three main phases: Dependencies, Test, and Deployment.


This phase is for installing any Ruby Gems, CocoaPods, Node Modules, and/or other packages your build needs.


This phase is for building and testing your project.

For iOS projects, we will generate a command to build and test your project using the xcodebuild command line tool. The command we generate is similar to:

set -o pipefail &&
    -sdk iphonesimulator
    -destination 'platform=iOS Simulator,OS=9.0,name=iPhone 6'
    -workspace MyWorkspace.xcworkspace
    -scheme "My Scheme"
    clean build test |
      tee $CIRCLE_ARTIFACTS/xcode_raw.log |
      xcpretty --color --report junit --output $CIRCLE_TEST_REPORTS/xcode/results.xml

If your project uses React Native, we will also automatically run the test script phase from your package.json.

Code Signing

We can automatically inject your code signing certificates and unlock the keychain for your build.

To use our automated code signing support for your iOS app, perform the following steps:

Export your certificates (p12)

Open Keychain, and select My Certificates in the menu on the left hand side.

Keychain with the keychain that contains the keys, and My Certificates selected

You should then be able to see a certificate with iPhone Developer: or iPhone Distribution: Select the certificate, then select File -> Export Items from the macOS Menu Bar.

The Keychain file menu with Export Items in a hover state

Ensure that the file format is Personal Information Exchange (.p12). If the option is not available, you probably forgot to select the private key when you selected the certificate.

The Keychain Export dialogue

You will then be asked for a certificate export password. This is not required, but we do recommend it.

Adding your certificate

Go to your project page on CircleCI, and open the Project Settings, then go to OS X Code Signing in the Permissions section.

The CircleCI Project Settings, iOS Code Signing page

Click Upload Key and enter the details for your certificate, including the password you used when exporting the .p12.

The CircleCI Certificate Details

Select the .p12 file you wish to upload and click upload.

The uploaded p12 certificates will be installed into circle.keychain as part of your build setup. The password for this keychain is circle, and it is unlocked for the duration of the build.

This keychain is also added to the Xcode search path, so any credentials stored here will be available to Xcode.

Using your provisioning profile

To use your provisioning profile with your CircleCI builds, you need to upload the .mobileprovision file on the Project Settings > OS X Code Signing page. Any provisioning profiles will automatically be added to the circle.keychain at the start of the build.

Customising your build

Although our inference will work for many cases, some teams may want to customise their build process to use custom tools or run their own scripts. This is done using the circle.yml file.

If you wish to see a more detailed guide to the format, take a look at our configuration sample.

Machine Configuration

Sometimes you’ll want to pin your build to either an older version of Xcode or a version in beta. You can do this by configuring a machine section in your circle.yml.

To do so, add a root level machine section to the document with a nested Xcode and version section:

    version: 8.0


If you have dependencies from homebrew or wish to have more control over dependency installation, you can override our commands:

    - brew install kylef/formulae/swiftenv
    - swiftenv install 3.0

The dependencies section also lets you run commands before or after our inferred commands:

    - gem install bundler --pre # Use a beta version of Bundler
    - make bootstrap


If you wish to override your test build phase, you can override our inferred commands with a test override. Every command here will be run regardless of previous failures.

    - swift test


If you wish to deploy your application with CircleCI, we recommend using Gym and Deliver from Fastlane.

Deployments can be defined by specifying an identifier, a branch or pattern that the release should run on, and a set of commands to run the release.

    branch: develop
      - fastlane release_staging
    branch: master
      - fastlane release_beta
    branch: release
      - fastlane release_appstore