Configure Bots to Perform Continuous Integrations

Bots are processes that Xcode Server runs to perform integrations on the current version of a project in a source code repository. An integration is a single run of a bot. Integrations consist of building, analyzing, testing, and archiving the apps (or other software products) defined in your Xcode projects. With Xcode Server 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 create a bot to perform integrations. You can choose when a bot performs 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 Xcode Server 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 checkbox for the scheme to share, and click Close.

    ../art/xcode_scheme_sharing_2x.png

     

  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 and Push” button.

Schemes are an important part of the Xcode build system. You can learn more about schemes by reading Scheme Configuration Help [link to about article, not just to the help book TOC]. For the purposes of using continuous integration, however, the important task is to set the chosen scheme to be shared and checked into the repository for the bot to use. For more information about managing schemes, see Scheme Editor Help.

Create Bots

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

To create a bot

  1. On your development Mac, open the Xcode 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.

    ../art/xcode_create_bot_attributes_2x.png../art/xcode_create_bot_attributes_2x.png
  3. Click Next.

    If you have not already added your repository to Xcode in Accounts preferences, enter your authentication credentials when prompted and click Next.

    ../art/xcode_create_bot_permissions_2x.png../art/xcode_create_bot_permissions_2x.png
  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.

    ../art/xcode_create_bot_schedule_2x.png../art/xcode_create_bot_schedule_2x.png
  5. Specify bot actions by clicking the appropriate checkboxes.

    You can enable static analysis, 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 be tested on.

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

    ../art/xcode_create_bot_devices_2x.png../art/xcode_create_bot_devices_2x.png
  9. Click Next.

  10. Bots can be configured to initiate triggers before and after integration. By default, a bot includes a notification trigger, which alerts committers if there is a failure. Specify who should receive email notifications from the bot (such as the notification shown in the screenshot below).

    ../art/xcode_create_bot_triggers_2x.png../art/xcode_create_bot_triggers_2x.png
    ../art/BotBlameEmail_2x.png

    If desired, you may configure additional triggers to run before or after integration. A trigger may be an email notification or a shell script.

    Post integration triggers may be configured to run conditionally, such as on success, on test failures, on build errors, on build warnings, or on static analysis warnings.

  11. Click Create Bot.

As explained in the following chapter, you can use the report navigator to manually start the bot, edit the bot, and delete it. As explained in 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 guidelines:

For detailed information on the extensive testing capabilities in Xcode, please refer to Testing with Xcode.