Configure Bots to Perform Continuous Integrations

Bots are processes run by the Xcode service to perform integrations on the current version of a project in a repository. Integrations consist of building, analyzing, testing, and archiving the apps (or other software products) defined in your projects. With the Xcode service able to access the source code repositories of those projects, you can configure bots to perform continuous integrations on them.

On a development Mac, a scheme defines what operations are performed by an integration. To automate an integration, you share its scheme and you create a bot to perform scheduled integrations. A bot can automatically perform integrations:

Share Build Schemes

A scheme specifies which targets to build for a project, which build configuration to use, and which executable environment to use when the product is launched. When you create a new iOS or OS X project, Xcode creates a default scheme that includes settings to perform these actions:

For the Xcode service to perform these actions, you must share their scheme. A shared scheme is one that you publish in a repository, along with the other shared project files.

To share a scheme

  1. On your development Mac, check out and open the project that contains the scheme to share.

  2. Choose Product > Scheme > Manage Schemes.

  3. Select the Shared option for the scheme to share, and click OK.

  4. Choose Source Control > Commit.

  5. Select the Shared Data folder.

  6. Enter your commit message in the text field.

  7. Select the “Push to remote” option (if your project is managed with Git).

  8. Click the Commit Files button.

For more information about managing schemes, see Scheme Configuration Help.

Create Bots

After sharing a scheme, create a bot to perform the integrations.

To create a bot

  1. On your development Mac, open the project containing the scheme that defines the actions to automate.

  2. Choose Product > Create Bot, and specify the identifying attributes of the bot.

    Leave the “Integrate immediately” option enabled to see the results of your first integration in the log navigator.

  3. Click Next.

    If you have not already added your repository to Xcode in Accounts preferences, enter your authentication credentials as prompted.

  4. Specify an integration schedule by using the Schedule pop-up menu.

    You can schedule the bot to perform its integrations periodically (hourly, daily, or weekly), on every commit, or manually.

  5. Specify bot actions by clicking the appropriate checkboxes.

    You can enable static analyis, unit testing, and product archiving.

  6. Choose whether to clean products before building.

    When performing a clean integration, the bot won’t reuse the previous build. Use the Cleaning pop-up menu to specify the frequency with which to clean: before each integration, once a day, once a week, or never.

  7. Click Next.

  8. For an iOS app, choose what kinds of devices or simulators the bot will test on.

    The devices must be connected to the server for the test action to complete.

  9. Click Next.

  10. Specify who should receive email notifications from the bot (such as the notification shown in the screenshot).

  11. Click Create Bot.

As explained in the following chapter, you can use the log navigator to manually start the bot, edit the bot, and delete it. As explained in “Manage and Monitor Bots from a Web Browser,” you can also use a web browser to manually start the bot, edit the bot, and delete it.

Follow Best Practices

To take advantage of continuous integration in your product development workflow, follow these practices: