util/gerrit-bot/README.md

   1 ## Gerrit Bot
   2
   3 ### Getting Username and Password
   4 Gerrit REST API uses the account username and password for the authentication
   5 purpose. They are necessary to make a request.
   6
   7 The following are steps to obtain the username and password from `.gitcookies`
   8 files,
   9
  10 * Follow this link
  11 [https://gem5-review.googlesource.com/new-password](https://gem5-review.googlesource.com/new-password)
  12 and copy the authenticating script to a new file.
  13
  14 * After that, run the `extract_gitcookies.py` to extract the username and
  15 password from the authenticating script.
  16 For example, the following command extracts the username and password from
  17 `gerrit_auth_script` and writes them to `.data/auth`,
  18 ```sh
  19 python3 extract_gitcookies.py gerrit_auth_script .data/auth
  20 ```
  21 The `.data/auth` will have two lines: the first line contains the username and
  22 the second line is the corresponding password.
  23 **Notes:**
  24 * The above link, [https://gem5-review.googlesource.com/new-password](https://gem5-review.googlesource.com/new-password),
  25 generates a new pair of username and password per visit.
  26 * The `extract_gitcookies.py` file is also able to read from `.gitcookies`
  27 file. For example, `python3 extract_gitcookies.py ~/.gitcookies output`
  28 will write all pairs of username and password in two lines per pair to
  29 `output`.
  30 * The gerrit-bot only reads the pair of username and password appearing
  31 in the first and the second line in the `.data/auth` file.
  32
  33 ### Gerrit Bot
  34
  35 The structure of the Gerrit bot is as follows:
  36 * The `GerritBotConfig` class should contain all constants that are
  37 configurable prior to running.
  38
  39 ### Gerrit API
  40 * Query options: [https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#query-options](https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#query-options)
  41
  42 ### Deployment
  43 The Gerrit bot is intended to be run as a cron job.
  44 Each run of the Gerrit bot will query new changes made to the Gerrit server
  45 within a certain period of time, perform actions on each change, and exit.
  46
  47 The following are steps to deploy the Gerrit bot:
  48
  49 * Create `.data` folder in the same folder as `bot.py`,
  50 ```sh
  51 mkdir .data
  52 ```
  53
  54 * Follow the steps [here](#getting-username-and-password) to get the Gerrit
  55 bot account username and password.
  56
  57 * To run the Gerrit bot once,
  58 ```sh
  59 ./bot.py
  60 ```
  61
  62 * To edit the cron table,
  63 ```sh
  64 crontab -e
  65 ```
  66
  67 To run the Gerrit bot every 30 minutes, add the following line to the
  68 crontable,
  69 ```python
  70 */1 * * * * cd /path/to/gerrit/bot/directory && ./bot.py
  71 ```