Start Building for Free

iOS Project Tutorial

4 weeks ago1 min read
On This Page

This document describes how to automate builds, testing, and deployment of an iOS application project with CircleCI in the following sections:

Note: There is also documentation for testing iOS and getting started on MacOS.


The following sections walk through how to write Jobs and Steps that use xcodebuild for this application, how to set up code signing and a provisioning profile in the CircleCI environment, and how to deploy with Fastlane.


  • Add your project to CircleCI, see Hello World.
  • This tutorial assumes you have an Xcode workspace for your project with at least one shared scheme and that the selected scheme has a test action. If you do not already have a shared scheme, you can add this in Xcode by completing the following steps:
  1. Open your Xcode workspace or project.
  2. Use the scheme selector to open the Manage Schemes dialogue box as shown in the following image. Xcode Scheme Selector
  3. In the manage schemes dialog, select the scheme you wish to build, and ensure that the Shared checkbox is enabled. Manage Schemes Dialogue
  4. Commit and push the schemes.

Running tests

For iOS projects, it is possible to run your tests with Fastlane Scan as follows:

      xcode: 12.5.1
      - run:
          name: Run tests
          command: fastlane scan
            SCAN_DEVICE: iPhone 6
            SCAN_SCHEME: WebTests

Refer to the Xcode version section of the iOS testing document for the complete list of supported versions.

Code signing and certificates

Refer to the code signing doc for details.

To further customize your build process to use custom tools or run your own scripts, use the config.yml file, see the Sample 2.0 config.yml document for customizations.

Installing dependencies

To install dependencies from homebrew, for example, use a run step with the appropriate command:

      - run:
          name: Install Homebrew Dependencies
          command: brew install yarn
      - run:
          name: Install Node Dependencies
          command: yarn install

Running tests

The run step is also used to run your tests as in the following example of the short form run syntax:

      - run: fastlane scan


To deploy your application with CircleCI using Gym and Deliver from Fastlane specify an identifier, a branch or pattern that the release should run on, and a set of commands to run the release.

version: 2.1
      xcode: 12.5.1
      - checkout
      - run: fastlane scan
      xcode: 12.5.1
      - checkout
      - run:
          name: Deploy
          command: fastlane release_appstore

      - test
      - deploy:
              only: release

Advanced configuration

See the Testing iOS Applications on macOS document for more advanced details on configuring iOS projects.

Example application on GitHub

See the circleci-demo-ios GitHub repository for an example of how to build, test and sign an iOS project using Fastlane on CircleCI.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.