Git Product home page Git Product logo

buildasaur's Introduction

Buildasaur

satellite badge Latest Buildasaur Release License

Twitter Buildasaur Join Slack

Automatic testing of your Pull Requests on GitHub and BitBucket using Xcode Server. Keep your team productive and safe. Get up and running in minutes.

(Follow Buildasaur on Twitter for infrequent updates.)

๐ŸŽ“ New to Xcode Server/Bots?

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

๐Ÿ”ฉ Configurable

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.

๐Ÿ‘€ Glanceable

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.

:octocat: Supported Git Hosting Services

  • GitHub
  • BitBucket
  • (are we missing yours? Create an Issue and I'll see if I can add it)

โฌ‡๏ธ Getting Buildasaur

  • just download the .app of the latest release, which will offer to automatically update itself as new releases become available
  • clone this repository, run fastlane prebuild and run it in Xcode (more work)

๐Ÿ”จ Requirements

  • Mac running at least OS X 10.11
  • Xcode Server (see my tutorials if you're new to Xcode Server)
  • your projects hosted on GitHub or BitBucket

๐Ÿ“˜ Xcode Versions

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 last supported
Xcode 7 โœ… latest
Xcode 6 โœ… 0.2.9

โœ… Installation Steps

  1. Install Xcode Server
  2. Download Buildasaur
  3. Setup Buildasaur
    • Checkout your project's repository locally over SSH
    • Launch Buildasaur
    • Click "New Syncer", which will guide you through setting one 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)

Features

๐Ÿ”ƒ Default workflow

The default workflow is as follows:

  • a Pull Request is opened by its author, Buildasaur creates a new 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/BitBucket 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 automatically gets performed and reported
  • when the PR is merged or closed, the Bot gets deleted automatically
  • if you require a different workflow, create an issue and we'll figure something out

๐Ÿ”“ The "lttm" barrier

  • "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
  • useful for projects that take longer time to run tests

โœ‰๏ธ Posting Status Comments

  • Buildasaur by default posts a comment into the PR conversation when an integration finishes

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

โœ๏ธ Manual Bot Management

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.

๐Ÿ‘“ Branch Watching

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 that 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.

Note that Branch Watching is only supported for GitHub-hosted projects.

๐Ÿšฆ Build Badges

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.

๐Ÿ’— Heartbeat

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 and type 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.

Despite absolutely no identifiable data being sent, if 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.

โš ๏ธ Troubleshooting

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/Logs, 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/, which is also what you might want to back up or migrate if you're moving your setup between machines.

Version 0.8.0 adds Crashlytics, so I receive crash reports. If you 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.

โ†ช๏ธ Looking for Xcode Server SDK?

The code for communication with Xcode Server lives in a project called XcodeServerSDK.

๐Ÿ’™ Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

๐Ÿ’ Contributing

Please create an issue with a description of your 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!

๐Ÿ’ฌ Slack

If you would like to be part of the Buildasaur community; feel free to join our Slack Team here.

โœŒ๏ธ License

MIT

๐Ÿ‘ Special Thanks

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

๐Ÿ‘ฝ Author

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

buildasaur's People

Contributors

antondomashnev avatar brett-best avatar cojoj avatar czechboy0 avatar delebedev avatar esttorhe avatar hallc avatar higgcz avatar joelekstrom avatar mdio avatar voidrender avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

buildasaur's Issues

Identify bots not by name but by a custom key

To allow #64 and #29, we need to uniquely identify bots by not their name. Instead, see if we can add a custom key to the bot's json when we're creating it, which would also get returned when we're fetching bots. If so, we could just add the identifier there and the name would be free to be whatever users want.

New status comment format (details of warnings, errors, test failures)

It would be great to report failed tests, errors and warnings in detail in the GitHub comments already.

Test failures: we receive in the integration object.
Warnings/errors: we need to make an extra call to the integration's /issues endpoint.

  • required refactor + tests: #184
  • add object that constructs the new comments with input data
  • pipe through the logic for asking for details of issues if build summary tells us that there was at least one error or warning)
  • only report the most serious problem (e.g. don't report warnings when a test failure or error occured)
  • split test (failure) information per device
  • add which devices the tests ran on

Currently blocked by

  • rdar://23142264 (Integrations endpoint doesn't return test result when asked for >1 integration)

Run as a daemon

Allow buildasaur to be setup as a daemon in order to run headless.

Possible ideas:
https://github.com/modcloth-labs/github-xcode-bot-builder
https://github.com/modcloth-labs/XBotBuilder

In this kind of setup possibly there would be no need to check out the Xcode project and workspace, but the configuration can be described into a file.

//Additional improvement:
When the server running buildasaur is restarted, there is no way to have buildasaur running without manual intervention.

Even when automatically login with an user and having buildasaur in the launch items we have to click on three buttons: Xcode server config, github config and start to have buildasaur working.

This is not the best situation in an automated environment.

Specify bot names in the UI

Right now, the bots are automatically named BuildaBot [organisation/repo] PR #pr-no. In our office, we have all integrations showing up on a big screen, and in this case these bot names make no sense.

It would be nice to be able to specify bot names with a small DSL in a field. Especially, more interesting than the PR number is to have the actual PR title.

Suggested solution

Add a text field in the UI where we can input names. Also, supply a few variables that can be used in the string that will be replaced if they exist. For example, the following input:

BurgerBot :: "{pr_name}" (#{pr_no})

where {pr_name} and {pr_no} are variables, would generate this bot name:

BurgerBot :: "Flip burgers twice instead of once" (#3)

Additional variables could for example be organisation, repo etc.

Allow automatic start of builds after pull request has been opened

Hi, Honza.
You probably already anticipated it, so here's the request for the possibility to remove the "lttm barrier". :)

We're using your awesome tool for our pull requests which go to private repositories with only trusted users to access them.
Forgetting to type lttm leads to no hints at all of any failed tests.

Right now we simply return isEnabled: true from isBotEnabled() in our own build of Buildasaur but it would be nice if you could incorporate that as an option so we won't have to modify your code after each update.

Add support for PRs across forks

Currently Builda fails because it can't find the PR branch, because it lives in a fork instead of the original repository. I need to find a way to detect that case and create the bot with the correct origin URL and such.

Optionally create an archive/IPA for OTA installation from a PR

It would be nice to have a way to also archive certain PR's code, so that it can be installed OTA from Xcode Server and tested on a device quickly (for UI changes).

Control over this would preferably be in the UI, so now users comment "lttm" to start testing a bot, there would be another keyword, like "archive", which would switch the Build Template to one that uses an Ad Hoc provisioning profile for the Archive action.

This would basically require a Build Template to be tagged as "adhoc" or each Build Template would have an optional property of "adhoc-scheme", which it could use in this case. This needs more thought, but should be pretty useful.

Add logging into a file

Mostly for debugging purposes, it'd be nice to have Builda logging all of its logs into a file instead of just the standard output.

Xcode 7 support

Xcode Server that shipped with Xcode 7 breaks Buildasaur, because the API version has been upped.

Back to reverse engineering.

Update UI to support multiple repositories

I have some ideas for how the UI should look in Buildasaur. Right now it looks very crammed, lots of info that doesn't really need to be shown. I started working on migrating it to how I would like it to look, but I won't put too much work until I know what direction @czechboy0 wants to take.

Anyway, I've used the OS X user settings pane as a basic guide:

skarmavbild 2015-06-16 kl 10 11 34

In Builda, this roughly translates to having a list of repos on the left side, and +/- buttons to add/remove them as needed.

What's more important is the right side. Right now, the Builda UI shows 3 different things on the main screen - project setup, server setup and console/running status. These 3 things should be 3 different top tabs in the new UI. No need to show them all at once, and it will make a much more pleasant and light default view.

Builda is also showing a bunch of settings buttons today, which really could go in an advanced settings page for the repo. Maybe something like the gear in the list to the left in the example above.

@czechboy0 What do you think? Is this a direction you'd like the Buildasaur UI to take?

Report code coverage in github comments

Pull code coverage information out of the build results and add it to the comment in the PR, so that users can see if a particular integration/PR is making code coverage better or worse.

Support for SSH passphrases

When generating SSH keys, you can optionally enter a passphrase. When setting up bots in Xcode, and setting credecentials -> Existing SSH keys, there is a field to enter this passphrase so Xcode can decrypt the keys.

There is no such field in Buildasaur, and when trying to use encrypted keys, buildasaur will say "Verified access, all is well" but all bots will fail to check out.

Suggested solution: Add a passphrase field and forward it to the Xcode bots if not left empty.

Bitbucket Support

Is there any merit in adding support for BitBucket pull requests into Buildasaur?

Update branch's commit statuses based on a non-PR bot

Think about how we could also add a syncer for not just PRs, but only for a "monitored" branch, e.g. master. A way to monitor a branch with a bot and to update the commit's status based on the bot's result. Would require a slight refactor where we'd allow the syncer to instead of resolving (PR + Bot) pairs to (branch + Bot) pairs, where PRs would just be one source of the monitored branch and we might have the user manually specify another, non-PR'ed branch to also be monitored and updated on GitHub.

  • Split the main syncer into multiple classes
  • Migrate to a SyncPair process, where each pair (Bot + PR, No Bot + PR, Bot + No PR) has its own class that handles its actions. Will scale better for new syncable pairs (Bot + Branch, ...)
  • Add tests for the right SyncPair creation based on inputs from GitHub and XCS
  • Introduce a Bot + Branch Sync Pair, which will share a lot with Bot + PR, share as much as possible
  • Add a way in the UI to mark particular branches to be synced permanently (no need for a PR)
  • Answer the question: will we allow picking a different Build Template for synced branches?
  • Enable this on master here in Buildasaur and test that it works well for a couple of days

Extract BuildaCiServer

I'd be really nice to extract whole BuildaCIServer to separate framework. Also CocoaPods and Carthage support are welcome.

I think that this implementation bring a lot of possibilities as you've captured a big part of Xcode Bots API in a nice container called XcodeServer.

A lot of people can take benefit from this and create other tools allowing them to use Xcode Bots from the outside of Xcode.

Support multiple repositories

You asked for it. ;)

It would be nice to be able to watch multiple repositories at the same time from the same machine.
Maybe a simple approach would be to allow multiple instances of Buildasaur running at the same time.

The only problem would be the 5000 requests limit which are used up by all instances but then one could simply configure each instance to poll less frequently.

Adaptive sync interval

Find a way to gradually slow down the sync interval when we're approaching the GitHub rate limit. So the sync interval set by the user is the minimum time between two syncs, but not the maximum - we might slow down to not hit the rate limit before the hour is over. Will become more important with multi syncer support and branch tracking, but would be good to know Builda is never blocked by just plain waiting for the rate limit to catch up.

Check if supplied GitHub account has read and write access to the repository

We ran into a problem with our private repository and the GitHub user account used for Buildasaur had read only access to the repository.
Credential validation from Buildasaur was successful and Bots were created, integrations ran.
But posting the integration result to GitHub and adding the comment failed and it took us a while to figure out why.

It would be cool if Buildasaur could check for write access as well and at least warn that integration results cannot be published on GitHub without write access.

Incorrect comment info

When manually triggering an integration on the pull requests bot (no code changes between the first integration and the manual one being triggered), buildasaur post on GitHub a comment with the info about the first integration instead than about the last one.

The same happens when triggering a third integration manually.

I am almost sure this is caused by having no code changes in between those integration.

Add Blueprint validation with xcsbridge source-control

See $ man /Applications/Xcode.app/Contents/Developer/usr/bin/xcsbridge for documentation on xcsbridge. It might be useful for blueprint validation and preflighting, making sure that the blueprint we're creating a bot with will indeed succeed. Will require a way to trigger a shell script from Swift and wait for its result. This might be a good way to catch invalid SSH keys etc before we create an invalid bot!

Create an issue when a tracked branch (with no PR) starts failing tests

Dependency: #18. Builds extra features on top of it.

Not just make Builda mark the commit appropriately on GitHub, also (optionally) create an issue if a watched branch suddenly starts failing tests (something like [Buildasaur]: Build failing on branch master) and comment what tests are failing exactly/what build error was emitted.
Then, when a new commit comes in that fails again, add a new comment with the new details (like we do with PRs).
Then, when a successful commit is pushed, comment that the issue was resolved and automatically close the issue.

  • Add functionality to:
  • Get open Issues
  • Create a new issue
  • Close an issue
  • Add logic for creating the Issue when a tracked branch fails, mark the issue with a special label so that we can then only fetch these ones instead of all open Issues (reference 1, reference 2)
  • Add logic for finding an existing matching issue (pull all open Issues with the special label first), create one if none exists
  • Make sure the PR logic for only posting a comment if it hasn't done so etc is working
  • Add logic for closing the Issue when the branch succeeds again

Add Xcode 7 certificate fingerprint validation UI

As part of #78 I had to disable SSH key validation due to the new server fingerprint validation kicking in. Let's bring it back, as it's a nice feature (to validate keys before confirming that all credentials are ok).

Permission-based "lttm"

For large open source projects - only allow repo's owners to "lttm" pull requests, so that random people can't lttm their own PRs if they are not owners.

Implementation
Look at the comment poster and figure out, whether they belong to the set of owners of the repo.
Actually, let's base it on Collaborators.
Ha! There's a really easy way to check whether a user is a collaborator.

Steps

  • Add a toggle for using Collaborator-based "lttm" (Not sure if necessary, should probs always be on)
  • When checking the enabled state of a bot, first filter only the comments made by collaborators and then look for "lttm" (so that anyone else's potentail lttm would be ignored)
  • Catch when a non-collaborator tries to "lttm" and post a comment informing them they can't do that as non-collaborators. (Maybe)

Check out repo in a temp location just from URL

This is to make setting up Builda even easier. Instead of having to have user's project to be tested checked out locally (so that Builda can parse the Xcode project and other files), make it check out the project in a temp location just from the URL and credentials.

Possible issue: how to force Xcode to create the .xccheckout file if it's not there?

Look into xcscmblueprint, #89.
Is there a way to force xcode to create the xcscmblueprint or xccheckout files?

  • Configure the script to checkout the repo in a temp location from the blueprint
  • Add this to the onboarding step when choosing projects (offer to pull from GitHub directly)

Request/response caching

To save rate limit hits, GitHub recommends using conditional requests, so that when nothing changes, no data is returned (only a special code). Look into using either a built-in solution (NSURLCache) or writing something from scratch. This will help to save a significant portion of now-consumed hits, allowing for a bright future with multiple project support and more features, while staying safely under the rate limit.

Infer and automatically filter devices based on target type

Pull from scheme -> id -> project -> buildConfigurations -> take first -> find XCBuildConfiguration. Look for IPHONEOS_DEPLOYMENT_TARGET and MACOSX_DEPLOYMENT_TARGET (probably also something like WATCHOS_DEPLOYMENT_TARGET. This should indicate the type of a target.

Allow customizations of the Bot name

Right now when I go to the Xcode Server web site (where you can download/install integration builds), it shows me a long list of bots that all look like:

BuildaBot [mozilla/firefox-ios] PR #498

I would like to customize this name so that it shows something like:

PR #409 Do not stop system audio on start

(I don't care about the repo name or the BuildaBot static string).

Ideally this can be configured with some really simple template string like PR #{{PR_NR}} {{PR_TITLE}} so that people can customize in different ways?

Disable URL caching to always get the latest data from GitHub (comments, statuses)

The default NSURLSession's configuration respects GitHub's response TTL, which is up to 60 seconds. However, if we want to sync more often (GitHub's authenticated rate limit is 5000 requests per hour, which is plenty to make Buildasaur very responsive to the team's workflow, when the sync interval is lower, cca 15sec), currently we get the same, cached response for ~4 more syncs, leading to duplicate comments etc. We need to disable the cache to always get the uncached state of the PR (status and comments, most importantly)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.