I'm your friendly neighbourhood bot, Tom. I trigger pull requests when someone mentions me in a GitHub Pull Request.

If you have valid config and secrets in the current working directory, you can run:

$ python3 -m tom --directory . --log-level info --interactive

(This assumes running in the repo folder, ., and interactive so you will be prompted before any actions are taken).

Example on our (private) Jenkins:

$ ssh ci.cfengine.com
olehermanse@jenkins:~$ sudo su tom
tom@jenkins:/home/olehermanse$ cd ~/
tom@jenkins:/home/tom$ python3 self/tom --log-level INFO
[INFO] Fetching pull requests for cfengine/documentation
[INFO] Fetching pull requests for cfengine/starter_pack
[INFO] Fetching pull requests for cfengine/masterfiles
[INFO] Fetching pull requests for cfengine/buildscripts
[INFO] Fetching pull requests for cfengine/core
[INFO] Fetching pull requests for cf-bottom/self
[...]

See the example policy for an automated way to update and run Tom.

To disable policy when testing, you can delete this flag file:

$ cd /home/tom
$ rm TOM_ENABLE

The TOM_ENABLE file is checked by the policy, not the python code. To re-enable:

$ cd /home/tom
$ touch TOM_ENABLE

See our commited config file for an example of what the JSON config file looks like. Note that one config file has multiple "bots", with unique GitHub usernames. Each of those "bots" can be configured to use different Jenkins instances, and separate secrets.

Secrets should be kept separate from the rest of the config. The filenames are specified in config.json. It is generally recommended to not commit secrets to git repos. Here is an example of what the secrets file can look like:

{
  "GITHUB_TOKEN": "46fb3751dd0d84cb02f8d8fc68d34ffed3247c4b",
  "JENKINS_USER": "a10062",
  "JENKINS_TOKEN": "de351e7ad2bcb3b2bdca23c5537e054c",
  "JENKINS_CRUMB": "814eeba4337de1f669643c1091aecb59"
}

(The secrets above are fake).

Explanation:

• GITHUB_TOKEN - API token generated by GitHub, for the bot username, specified in config.json.
• JENKINS_USER - Jenkins username (LDAP username in CFEngine Jenkins).
• JENKINS_TOKEN - API token, generated in Jenkins Settings UI.
• JENKINS_CRUMB - GET https://<jenkins>/crumbIssuer/api/xml (for CFEngine: https://ci.cfengine.com/crumbIssuer/api/xml).

Most of the codebase works by polling open pull requests, rather than having a web server wait for Webhooks. There is one exception, the optional slack bot, which can be triggered from mentions in Slack.

See run_tests.sh here for a development workflow working with pytest unit tests.

Open htmlcov/index.html to see python code coverage information after test runs.

pass a test name to run_tests.sh and it will only run that one test.