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:
Every time a change is published to the repository
On a regular schedule
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 unit test cases that you implement
Archive, which builds an archive of the product that the scheme built
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
On your development Mac, check out and open the project that contains the scheme to share.
Choose Product > Scheme > Manage Schemes.
Select the Shared option for the scheme to share, and click OK.
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 button.
For more information about managing schemes, see Scheme Configuration Help.
After sharing a scheme, create a bot to perform the integrations.
To create a bot
On your development Mac, open the 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 as prompted.
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 analyis, unit 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 test on.
The devices must be connected to the server for the test action to complete.
Specify who should receive email notifications from the bot (such as the notification shown in the screenshot).
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:
Develop unit-test suites and test cases. After developing unit 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 unit 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.
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.