Recently set up OS X Server, specifically Xcode Bots. I used the final version of Xcode 5.1, on Mavericks. This was my second time implementing Apple CI. If it's your first time doing so, I have some suggestions.

Rather than attempting to be a comprehensive how-to (which you can find fairly easily elsewhere), I'll go the prescriptive route and tell you some things you might want to consider doing.

Before you even install OS X Server and start with automation, make sure you can build in Xcode.

You are probably not setting this up on one of your team's development laptops, most likely it's a fresh machine. So I would suggest starting by installing Xcode from the Mac App Store. Whatever iTunes Store account you use will be required for updates (password prompt), so you might want to consider a dedicated account, set up with a Visa gift card or likewise.

You'll want to add the machine to your Apple developer account, and probably create a service account for it that's not tied to any given person. That theme comes up a lot--you don't want problems with things tied to any one individual. For the Apple Store account that requires a credit card, you may want to be lazy, but for the Apple Developer account, there's really no reason not to create a new one.

Download the provisioning profiles. If you have an enterprise cert, you'll need to eventually follow some steps to make it work with Bots.

Next, set up shared schemes if you don't already have them. If you do already have them, consider duplicating one of your existing schemes only for the purpose of CI. That way when you come upon changes that you need to make, you can do so without affecting the existing shared scheme.

Make sure you can Archive. Note that you have to select iOS Device before the Archive option shows up in the menu. If you've got this working, you set yourself up for success down the line.

Set up OS X Server and enable Xcode integration

This one is pretty straightforward. You need to purchase OS X Server for $19.99 in the Mac App Store and install it. Then you need to turn on Xcode integration. Select the main Xcode from Applications unless you really need to use a beta version.

There's some development team stuff here you'll need to do, like you did in the Xcode app. You'll likely want to add a git repository. In my case I'm using GitHub, so you'll probably want to create a service account with access to your code, and perhaps a separate team for that service account within your organization, if you have one. This will facilitate making sure the build machine has proper access without, again, being tied to an individual person's credentials.

Creating Bots--take your time

Image credit: John Liu

OK, at this point I don't think I've added that much value beyond what's already out there on the web. But what I'm about to tell you is the reason I decided to write this article.

Once you've got the repository added with the proper permissions so it can pull from your upstream, you're ready to create a bot. Here's where I did better the second time around. By default, you're going to be tempted to create a million bots and have them all run every possible step and email everyone every time anything happens. If you don't have a really beefy machine, this will likely completely overload it. Even if you're setting this up on a Mac Pro, I recommend starting slow so you feel in control and you can get used to the process. There's no hurry.

I recommend you create one bot to start, and only compile. Don't test, archive, analyze. Schedule it manually. Don't automatically run it on every commit. Don't have it email anyone at first, not even you. Set Cleaning to Never, to make it faster. And I even recommend not clicking the box that says "Integrate immediately".

This seems a bit overly cautious when I write it down, but it felt good when I did it. It allows you to build up an area of comfort and control and gradually engage as things prove stable. As with setting up Xcode and being able to Archive before you start automating, it allows you to get a series of small wins that keep you motivated and feeling good.

Kicking off that first integration by hand rather than automatically lets you get used to the environment, get used to the UI, and then deliberately progress to the next step and see what happens.

That's really all I wanted to say

If you start slow, it's really easy to go in and add more and do more. I found it a very rewarding experience the second time around, and it's super easy to go back and add additional build steps. However, there's another important reason why I find this valuable. It allows you to get to a steady state where this thing is useful and works and it does something and you can predict how it's going to work. And get there quickly. Also, because you understood one step before progressing to the next, you're going to have a good shot at fixing it easily if things do break.

What's the alternative

When I started the first time, I set up a half dozen bots and set them all to do all steps any time there was a commit. And email everyone. Then when things broke and the little machine got overloaded, it was very overwhelming. I had to dig through dozens of warnings and errors and it took a long time to whittle down and get rid of all the errors. Also, people on my team started getting emails about the build breakage, and I told them "it's not fully set up yet". This trained them to ignore build breakage emails. Not what you want.

Psychologically, it was just so much more satisfying to start small for me. I did several manual integrations, got things building. Great. Then I set it up on a separate 'canary' branch and enabled polling for new commits there. This was very helpful, because I could just force push to that branch and kick off a new build whenever I wanted. Handy way to check some code before you push to master.

Then I fixed some warnings. Then I set up polling for a lower traffic feature branch. Then finally I set up polling for master.

It's a small thing, but I think you'll find doing it this way to be very rewarding and satisfying.

Also, if you want to send emails from the box, you may want to follow this tutorial. Be aware that once you enable postfix, it will send any queued up emails Bots tried to send.

Hope this is helpful to someone. At the moment, I don't have analyze, I don't have unit tests, and I only have one app out of three in the repo building. But I'm happy with it.

Less functionality is less to break and less to maintain. But Xcode bots is actually really nice. And if you use JIRA, you can set up your bot to automatically email to create a ticket when the build is broken.

One last tip

Sometimes it seemed like an integration would hang. So I would quit OS X Server and re-start it. I realized after a while that wasn't doing anything. Server.app is just a UI. Flipping the toggle switch for the Xcode service, on the other hand, actually stops and re-starts the service, which got my stalled builds working again.

Good luck!