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.
Assumptions and prerequisites
When we run your project on macOS, 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 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.
In the manage schemes dialog, select the scheme you wish to build, and ensure that the Shared checkbox is enabled.
Finally, commit and push the schemes.
Builds are broken up into three main phases: Dependencies, Test, and Deployment.
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 && xcodebuild CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY= PROVISIONING_PROFILE= -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
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 Access.app, and select My Certificates in the menu on the left hand side.
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.
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.
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.
Click Upload Key and enter the details for your certificate, including the password you used when exporting the .p12.
.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 commit the
.mobileprovision file to your repository. Your 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
If you wish to see a more detailed guide to the format, take a look at our configuration sample.
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
To do so, add a root level
machine section to the document with a nested Xcode and version section:
machine: xcode: version: 8.0
If you have dependencies from homebrew or wish to have more control over dependency installation, you can override our commands:
dependencies: override: - brew install kylef/formulae/swiftenv - swiftenv install 3.0
The dependencies section also lets you run commands before or after our inferred commands:
dependencies: pre: - gem install bundler --pre # Use a beta version of Bundler post: - 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.
test: override: - swift test
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.
deployment: staging: branch: develop commands: - fastlane release_staging beta: branch: master commands: - fastlane release_beta production: branch: release commands: - fastlane release_appstore