tools/bionicbb/README.md

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