Repository files navigation

Homu is a bot that integrates with GitHub and your favorite continuousintegration service such asTravis CI,Appveyor orBuildbot.

Let's take Travis CI as an example. If you send a pull request to a repository,Travis CI instantly shows you the test result, which is great. However, afterseveral other pull requests are merged into themaster branch, your pullrequest canstill break things after being merged intomaster. Thetraditional continuous integration solutions don't protect you from this.

In fact, that's why they provide the build status badges. If anything pushed tomaster is completely free from any breakage, those badges willnot benecessary, as they will always be green. The badges themselves prove that therecan still be some breakages, even when continuous integration services are used.

To solve this problem, the test procedure should be executedjust before themerge, not just after the pull request is received. You can manually click the"restart build" button each time before you merge a pull request, but Homu canautomate this process. It listens to the pull request comments, waiting for anapproval comment from one of the configured reviewers. When the pull request isapproved, Homu tests it using your favorite continuous integration service, andonly when it passes all the tests, it is merged intomaster.

Note that Homu isnot a replacement of Travis CI, Buildbot or Appveyor. Itworks on top of them. Homu itself doesn't have the ability to test pullrequests.

Homu is largely inspired bybors. The concept of "tests should be done justbefore the merge" came from bors. However, there are also some differences:

1. Stateful: Unlike bors, which intends to be stateless, Homu is stateful. Itmeans that Homu does not need to retrieve all the information again and againfrom GitHub at every run. This is essential because of GitHub's ratelimiting. Once it downloads the initial state, the following changes aredelivered with theWebhooks API.
2. Pushing over polling: Homu prefers pushing wherever possible. The pullrequests from GitHub are retrieved using Webhooks, as stated above. The testresults from Buildbot are pushed back to Homu with theHttpStatusPushfeature. This approach improves the overall performance and the responsetime, because the bot is informed about the status changes immediately.

And also, Homu has more features, such asrollup,try, and the Travis CI &Appveyor support.

$ sudo apt-get install python3-venv python3-wheel$ python3 -m venv .venv$. .venv/bin/activate$ pip install -U pip$ git clone https://github.com/rust-lang/homu.git$ pip install -e homu

In the following instructions,HOST refers to the hostname (or IP address)where you are running your custom homu instance.PORT is the port the serviceis listening to and is configured inweb.port incfg.toml.NAME refers tothe name of the repository you are configuring homu for.

1. Copycfg.sample.toml tocfg.toml. You'll need to edit this file to set upyour configuration. The following steps explain where you can find importantconfig values.

2. Create a GitHub account that will be used by Homu. You can also use anexisting account. In thedeveloper settings, go to "OAuthApps" and create a new application:

   • Make note of the "Client ID" and "Client Secret"; you will need to put them inyourcfg.toml.
   • The OAuth Callback URL should behttp://HOST:PORT/callback.
   • The homepage URL isn't necessary; you could sethttp://HOST:PORT/.

3. Go back to the developer settings of the GitHub account you created/used in theprevious step. Go to "Personal access tokens". Click "Generate new token" andchoose the "repo" and "user" scopes. Put the token value in yourcfg.toml.

4. Add your new GitHub account as a Collaborator to the GitHub repo you aresetting up homu for. This can be done in repo (NOT user) "Settings", then"Collaborators". Enable "Write" access.

   4.1. Make sure you login as the new GitHub account and that youacceptthe collaborator invitation you just sent!

5. Add a Webhook to your repository. This is done under repo (NOT user)"Settings", then "Webhooks". Click "Add webhook", then set:

   • Payload URL:http://HOST:PORT/github
   • Content type:application/json
   • Secret: The same asrepo.NAME.github.secret incfg.toml
   • Events: click "Let me select individual events", then pickIssue comments,Pull requests,Pushes,Statuses,Check runs

6. Add a Webhook to your continuous integration service, if necessary. You don'tneed this if using Travis/Appveyor.

   • Buildbot

     Insert the following code to themaster.cfg file:

     frombuildbot.status.status_pushimportHttpStatusPushc['status'].append(HttpStatusPush(serverUrl='http://HOST:PORT/buildbot',extra_post_params={'secret':'repo.NAME.buildbot.secret in cfg.toml'},))

7. Go through the rest of yourcfg.toml and uncomment (and change, if needed)parts of the config you'll need.

$. .venv/bin/activate$ homu