README.md
1bionicbb
2========
3
4The bionic buildbot contains two services: a gmail polling service, and a web
5service that interacts with gerrit.
6
7Dependencies
8------------
9
10 * Python 2.7
11 * [Advanced Python Scheduler](https://apscheduler.readthedocs.org/en/latest/)
12 * [Flask](http://flask.pocoo.org/)
13 * [Google API Client Library](https://developers.google.com/api-client-library/python/start/installation)
14 * [jenkinsapi](https://pypi.python.org/pypi/jenkinsapi)
15 * [Requests](http://docs.python-requests.org/en/latest/)
16
17Setup
18-----
19
20Create a `config.py` in the same directory as the sources. The structure of the
21configuration file is as follows:
22
23```python
24client_secret_file = 'CLIENT_SECRET_FILE.json'
25build_listener_url = 'BUILD_LISTENER_URL'
26jenkins_url = 'JENKINS_URL'
27jenkins_credentials = {
28 'username': 'JENKINS_USERNAME',
29 'password': 'JENKINS_PASSWORD',
30}
31```
32
33The client secret file comes from the Gmail API page of the [Google Developers
34Console](https://console.developers.google.com/). The Jenkins credentials are
35for a Jenkins account that has the appropriate permissions to launch the jobs
36the buildbot will use.
37
38You will also need to add the HTTP password for the buildbot's Gerrit account to
39`~/.netrc`. The HTTP password can be obtained from the [Gerrit HTTP password
40settings](https://android-review.googlesource.com/#/settings/http-password).
41
42To launch the services:
43
44```bash
45$ python build_listener.py >build.log 2>&1 &
46$ python gmail_listener.py >mail.log 2>&1 &
47```
48
49The mail listener will direct your browser to an authentication page for the
50Gmail API.
51
52gmail\_listener.py
53------------------
54
55Bionicbb polls a gmail account to find changes that need to be built. The gmail
56account needs to have a gerrit account set up with project watches on anything
57it finds interesting. This is a rather ugly hack, but it seems to be the
58simplest option available.
59
60Gerrit does offer a streaming notification service that would be _far_ better,
61but it is only available over an SSH conection to gerrit, and the AOSP gerrit
62does not support this connection.
63
64Another option would be polling gerrit itself, but we'd have to process each
65change every time to see if it should be built, whereas project watches allow us
66to treat these as semi-push notifications (we still have to poll gmail).
67
68One drawback to this approach is that it's a hassle to set up the project
69watches for a large number of projects. Since bionicbb is only interested in a
70small subset of projects, this is a non-issue.
71
72If the buildbot has applied Verified-1 to a patchset, the user may add their own
73Verified+1 to the change and the buildbot will remove its rejection the next
74time the services polls (by default, every five minutes).
75
76The service will also listen for the following commands:
77
78 * `bionicbb:clean`: Something is very broken and the buildbot's output
79 directory needs to be nuked.
80 * `bionicbb:retry`: Something went wrong and the buildbot should retry the
81 build.
82
83build\_listener.py
84------------------
85
86The build listener service responds to HTTP POST events sent from Jenkins and
87updates CLs accordingly. The only other API endpoint is `/drop-rejection`, which
88will remove a Verified-1 from a previously rejected patchset. The actually
89invocation of this is handled by the gmail listener.
90