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:
Every time a change is committed to the repository
On a regular schedule, such as hourly, daily, or weekly
When manually initiated
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:
Analyze, which performs static code analysis
Test, which runs the test cases that you implement
Archive, which builds an archive of the product that the scheme built
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
On your development Mac, check out and open the project that contains the scheme to share.
Choose Product > Scheme > Manage Schemes.
Select the Shared checkbox for the scheme to share, and click Close.
Choose Source Control > Commit.
Select the Shared Data folder.
Enter your commit message in the text field.
Select the “Push to remote” option (if your project is managed with Git).
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.
After sharing a scheme, create a bot to perform integrations.
To create a bot
On your development Mac, open the Xcode project containing the scheme that defines the actions to automate.
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.
If you have not already added your repository to Xcode in Accounts preferences, enter your authentication credentials when prompted and click Next.
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.
Specify bot actions by clicking the appropriate checkboxes.
You can enable static analysis, testing, and product archiving.
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.
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.
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).
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.
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:
Develop test suites and test cases. After developing tests, include them in schemes for your bots to run. To help ensure that the changes you make aren’t broken by you or others later, complement those changes with tests that determine whether a method or a set of methods used in a sequence functions as intended.
Perform static analysis. Include static analysis in your integrations. Static analysis is a deep examination of your code, following code paths that your app may not follow during normal development. This process uncovers hard-to-find coding errors and also identifies areas in your code that don’t follow recommended API usage, such as Foundation and AppKit idioms.
Conduct performance testing. Configure Xcode to run performance tests for your apps on multiple devices. This will allow you to track your performance and identify potential problems up front, before distributing your product to users.
Ensure that your product builds and is packaged correctly. Archive your product after making major changes, especially structural changes, such as adding or removing files. Let your bots archive for you automatically. The ability to build and archive your product is a main indicator of the correctness of your code changes.
For detailed information on the extensive testing capabilities in Xcode, please refer to Testing with Xcode.