NOTE: This document was written with respect to Bamboo 4.4 and version 1.8 of the Xcode plugin. I'll update it to Bamboo 5 and v 2.1 soon.
Here's the process, from top to bottom, including my little discoveries along the way.
Install the Bamboo iOS, Cocoa and Xcode plugin
- First off, note that Bamboo has its own marketplace (as opposed to one for your JIRA instance). In order to do this, you need to be an administrator in Bamboo (but not JIRA).
- Navigate to Administration -> Plugins -> Find New Add-ons. Search Xcode and install the plugin. No additional configuration or plugin management needed here. This simply enables a few features like support for adding the iOS SDKs and Xcode tasks, which you'll get to later.
Creating a remote agent in Bamboo
- From the Administration tab, go to Agents and select install remote agent. You can install it wherever you'd like... I wouldn't recommend your downloads folder though. I put mine in /Documents/dev/bamboo-agent-home.
- If you have problems running your remote agent to the tune "Could not load properties", you may need to explicitly set your port number or open a port on your firewall. This Atlassian Support Q&A was helpful for addressing this issue.
- For more information see the Remote Agent Installation Guide.
Configuring Capabilities for your Remote Agent
- Agents use capabilities for two purposes, (1) to tell the agent what it can do, and (2) in order for jobs to identify which agents can run which build plans.
- Regarding point 1, you will now create two capabilities that will allow you to build you project for iPhone and for the simulator.
- From the Agents screen, select your remote agent
- Select Add Capability
- Select Xcode SDK as the compatability type
- Enter Simulator - iOS 6.1 as the SDK Name
- Enter iphonesimulator6.1 as the SDK Label. ****This part is what took so much time to figure out. In a couple of the blog posts out there it recommends using the command
- Regarding point 2, this is important because if you don't specify capabilities, your build plans will try to run on all agent that meet their basic requirements. In our case, our web team's build plan's requirements weren't set to the appropriate capabilities, so whenever a build occurred and the OSX remote agent was running, it would try to run on both agents, causing it to fail immediately on our remote agent. Note that custom capabilities are often used to control which jobs will be built by which agents, the most common one I've seen being an isLocal flag, which only allows the local agent to run the build plan.
- For more information see Agents and capabilities.
Connecting to your GIT repository
- After you have configured your remote agent, create your plan. This part is fairly straightforward, which the exception of connecting to your GIT repo, which can be tricky.
- In our case, a user named 'fisheye' has already been setup with the appropriate permissions and keys on neptune. Unless something has changed, don't worry about generating new ssh keys for yourself and putting them up on neptune. Have Jacob login and upload the private key for this user.
- Note that the repository URL should include ".git" at the end, i.e. ssh://something@path.com/home/git/myapp.git
Creating Tasks for Your Build Plan
- Task 1 - Source Code Checkout
- The first task you'll want to create is Source Code Checkout. Actually, it was probably done automatically. Make sure the repository is set to your project and run your build plan. You should be green.
- At this point, if you run into a NoClassDefFound error, check out this support Q&A. Basically, the fix is to downgrade your Xcode plugin to v1.8 and try again. You can download it at the link at the top of this post. To install it, within Bamboo go to Administration -> Plugins -> Manage Add-ons -> Upload Add-on. My guess is that the latest version of the plugin targets Bamboo 5.0 and at the time of this posting we are running Bamboo 4.4.4. The plugin says it supports 4.4... but yeah...no dice.
- Task 2 - Build the Xcode project
- Next up we want to create a task to build the Xcode project. This is where those iOS SDK capabilities that we setup earlier come back into play. The first thing to keep in mind here is that essentially all this task will do is build your project, the same way you would if you built it from terminal using xcodebuild, e.g. xcodebuild -sdk iphonesimulator6.1 -project PRTablet.xcodeproj -alltargets -configuration Release.
- My personal suggestion here is to forget Bamboo for a minute and try building your project from the command line. In our case, command line builds failed with compile errors because the main PRTablet target can't see the RestKit subproject files (despite it building correctly in Xcode). To get around this, you'll want to setup a workspace and scheme rather than an xcodeproj and target, which will build all projects in the same directory, referred to as the workspace build directory. Now, all of these files are visible to each project. Verify it now builds successfully from the command line, e.g. xcodebuild -sdk iphonesimulator6.1 -workspace PRTablet.xcworkspace -scheme PRTablet -configuration Release.
- Now that you know it will build successfully, create a second task under your build plan. Select Add Task -> Xcode. When you're done, it should look something like below.
- Save and run your build plan. If you got a "possible compilation error" check the logs. If it's an xcodebuild error: "The workspace does not contain a scheme named," you need to go back into your workspace, go to Manage Schemes... and check the Shared box next to your scheme. Push your code and run your build plan again (Bamboo may even do it automatically this time). You should now be green.
- Task 2.5 - Unit Tests
- To run have your agent execute your unit tests, you'll need to check the "Include OCUnit Test results" box above. See the Xcode docmentation. Note: I've been unable to get this working so far, since Bamboo for some reason is unable to see our unit tests. The error message reads "Failing task since test cases were expected but none were found." I found a support Q&A for this problem and added comment asking if anyone has found the fix.
- UPDATE: Looks like unit tests with a test host cannot be run in the simulator in v1.8 of the app. If you can, upgrade to v2.1. In versions 2.0+ of the plugin, you can use the ios-sim method to run application tests from the command line.