Free, local and automatic testing of GitHub Pull Requests with Xcode Bots. Keep your team productive and safe. Get up and running in minutes.

(Follow Buildasaur on Twitter for infrequent updates.)

To learn how to set up Xcode Server in minutes, check out my Xcode Server Tutorials.

Buildasaur was designed to be easy to setup, while still giving you all the customization you need. By choosing the right defaults, most teams can get Buildasaur set up in minutes, start it and never have to worry about it again.

Buildasaur runs as a background Mac app, its configuration window goes away when you don't need it. This gives you a chance to quickly peek at the status of your syncers from the menu bar.

You have multiple options of getting started with Buildasaur, from source code to downloading the App.

• get the .app of the latest release
• check out code and build and run in Xcode (Buildasaur is written in Swift 2)

• Xcode Server (see my tutorials if you're new to Xcode Server)
• your projects on GitHub
• starting with version 0.6.0, also OS X 10.11 (previous version required OS X 10.10)

Xcode Server ships in Xcode, so the server API is also dependent on the Xcode you have. See the table of latest Buildasaur versions supporting each Xcode version.

| Xcode | Buildasaur | | :-- | :--: | :--: | | Xcode 7 | ✅ latest | | Xcode 6 | ✅ 0.2.9 |

• Install Xcode Server

• Get a Personal token from GitHub

  • go to GitHub.com and when you're signed in, go to Settings -> Applications -> Personal access tokens -> Generate new token
  • leave the default rights and copy the token

• Buildasaur Setup

  • Checkout your project's repository locally over SSH
  • Launch Buildasaur
  • Click "New Syncer", which will guide you through setting it up
  • At the end of the flow, click "Start" to start syncing
  • You can add as many syncers (read: projects) as you want
  • You can close all Buildasaur's windows, it will keep running in the background (click on the menu bar icon to open the configuration window again)

The default workflow is as follows:

• a Pull Request is opened by its author, Builda creates a Bot
• if the "lttm" barrier (see below) is disabled, an integration is started immediately. if the "lttm" barrier is enabled, Builda waits until someone comments "lttm" in the Pull Request conversation (the "lttm" barrier is disabled by default, can be disabled in the UI)
• an integration (building, testing and/or archiving) is performed on the PR's branch
• result of the integration is reported back to GitHub by changing the status of the latest commit of the branch and posting a comment in the PR conversation (optional, enabled by default)
• if any additional commits are pushed, another integration gets performed and reported back
• when the PR is closed, the bot gets deleted automatically
• if you require a different workflow, create an issue and we'll figure something out

• "Looks Testable To Me"
• an optional extra step in the workflow (disabled by default starting from version 0.5.0, was enabled by default in previous versions)
• instead of integrating immediately after a PR is created, the reviewer first has a chance to look at the code and request any fixes of the code from the author
• when the reviewer is happy with the code visually, she comments "lttm" in the PR and the bot is activated and performs an integration of the code
• from that point on, if any additional commits are pushed, they get integrated as with the basic workflow

• Builda can (and by default does) post a comment into the PR conversation when an integration finishes

• this can be controlled in the UI with the toggle named "Post Status Comments"

In addition to automatic bot management with syncers, you can create bots from an existing Build Template and a branch by clicking Manual Bot Management when your syncer is setup. This is useful for creating one-off bots based on e.g. release branches with a different Build Template than you use for PRs.

All branches with open Pull Requests are automatically watched and tested. However, what if you wanted to watch a branch which does not have a Pull Request associated with it? Like master, or a release branch into which you're making final changes and want tested?

Buildasaur supports that. You can select extra watched branches, which will automatically be tested and their statuses will be updated on GitHub. You can see the statuses of Buildasaur's branches here, for instance.

Enabling watched branches is a prerequisite of getting build badges working with satellite.

I built a tiny service called satellite, which serves down badges based on GitHub status of a branch. And this status is automatically updated by Buildasaur when a build finishes (enable a watched branch in Buildasaur for whichever branch you'd like to base your badge on, usually master).

TL;DR? Just add this to your README and replace USER, REPO and BRANCH with your info. And you'll get a build badge like this:

[![satellite badge](https://stlt.herokuapp.com/v1/badge/USER/REPO/BRANCH)](https://github.com/USER/REPO/branches)

If you don't specify a branch, master will be used.

In order to understand how many Buildasaur instances are actively being used (which helps me to decide how much free time I should dedicate to this project) one anonymous heartbeat event is sent from Buildasaur every 24 hours (and one when Buildasaur is launched). There is absolutely no information about your projects being synced with Buildasaur (I don't care about that, that's your business), the event just sends a randomly generated identifier (to discern between different Buildasaur instances), the uptime of Buildasaur (to potentially detect crashes) and the number of running syncers.

I wrote the server storing this data myself - and it's open source, so feel free to take a peek yourself at how that's done. And take a look here to see exactly what data is being sent.

If, despite absolutely no identifiable data being sent, you still aren't comfortable allowing Buildasaur to send its heartbeat, add { "heartbeat_opt_out" = true } to ~/Library/Application Support/Buildasaur/Config.json. But please keep in mind that if you do that, it will make me think fewer people are in fact using Buildasaur, which might just lead to me spending less time on improving it.

If Builda crashes, you can find crash logs at ~/Library/Logs/DiagnosticReports/Buildasaur-*. Please let me know if that happens and I'll take a look. Also, Builda logs (pretty verbosely) to ~/Library/Application Support/Buildasaur/Builda.log, so this is another place to watch in case of any problems. You can find all persisted files that Buildasaur keeps around at ~/Library/Application Support/Buildasaur/.

Version 0.7.0 adds Crashlytics, so I'll get crash reports in such cases. If you'd prefer to opt-out of crash reporting, you can do so by adding { "crash_reporting_opt_out" = true } to ~/Library/Application Support/Buildasaur/Config.json.

The code to communicate with Xcode Server lives in the project called XcodeServerSDK. Buildasaur is just one app that uses this SDK, but now you can build your own as well!

Please create an issue with a description of a problem or a pull request with a fix. Or, if you just want to help out, take a look at issues with the label "up-for-grabs", comment on the issue that you're working on it and let's improve Buildasaur together!

MIT

• Vojta Micka (@higgcz) for our great new logo!

Honza Dvorsky - http://honzadvorsky.com, @czechboy0