gh-bot

gh-bot: Create your GitHub bot

gh-bot is a fully scriptable build/test bot for Github projects. It is similar to Travis-CI in purpose, but most of the action happens at the pull request level and there are no constraints on what types of tests you can run. (Also you have to provision your own test/build servers).

gh-bot is written in Node.js and works on all platforms Node.js and git run on.

This project is a fork of Bot.io that is optmized to work in 2021.

Please note that gh-bot requires a public (and static) IP address to work properly.

Improvements over bot.io

gh-bot is an improved version of Bot.io which adds the following features that aren't present in Bot.io

• TypeScript support
• Uses Octokit to access the API instead of fetching it
• Uses node-fetch instead of axios
• Easily extendable: Many classes are exposed to allow you to build your own app based on gh-bot
• Option to allow commands from everyone
• async JavaScript for speed improvements and cleaner code

And more!

How it works

Pull request testing

1. You write shell-like scripts such as on_cmd_test.js that tell the bot what to do when it receives a command. (Any arbitrary command can be defined).
2. Pull request reviewers leave a comment containing a bot command like /gh-bot test, causing the bot to run the corresponding script against a hypothetically merged pull request.
3. The bot reports back to the pull request discussion with a comment containing the test result, so reviewers can anticipate if the PR will break their master branch before merging it.

Other uses

• Live browser tests: gh-bot comes with a built-in web server, so if your project is a web app you can create a script, say on_cmd_preview.js, to deploy select files into the server. Reviewers can then issue /gh-bot preview and take the PR for a spin in their browser before merging it.

• Post-receive scripts: gh-bot scripts can do just about anything shell scripts can do, and they can hook into other Github events. For example, the script on_push.js is executed every time new commits are pushed to the master branch.

Getting started

gh-bot depends on Node.js and git. To get started, install gh-bot globally, create a new dir for your gh-bot files, and bootstrap the necessary files for your repo, for example:

$ npm install -g gh-bot
$ mkdir gh-bot-files; cd gh-bot-files
$ gh-bot bootstrap --repo arturadib/pdf.js

(Replace arturadib and pdf.js with your Github username and repo, respectively).

The bootstrapped file config.json contains sensible defaults, but you will likely want to double-check and/or modify it at this point. (In particular, make sure host, port, and whitelist are what you want). Then let gh-bot set up the necessary Github hooks, and start the server, for example:

$ gh-bot sethooks
$ gh-bot start

That's it! You can now trigger your first gh-bot job by leaving the following comment on any pull request in your repo:

/gh-bot test

The bot should write back a hello world response in the PR discussion. At this point you will probably want to customize your scripts, as described below.

Customizing

Writing bot scripts

When Github sends a new notification, gh-bot automatically fires up the corresponding script. For example, push (post-receive) notifications will trigger on_push.js, whereas a PR comment containg a command like /gh-bot preview will trigger on_cmd_preview.js.

If you want to write a script that triggers on pushes to branches other than master, simply name the file on_push_to_branchname.js.

gh-bot uses ShellJS to enable portable shell-like scripting, so your scripts look like traditional Unix shell scripts but work verbatim on different platforms (like Windows). See mozilla/botio-files-pdfjs for real-world examples.

When you require() the main gh-bot module, it automatically takes care of the necessary cloning and merging into a temporary (private) directory, and executes your script in that directory. The module also exposes the following job information properties:

ghbot.id              // Unique id string of the job
ghbot.event           // Event type (e.g. cmd_test, push, etc)
ghbot.issue           // Issue number (if event comes from issue comment or pull request)
ghbot.base_url        // Git URL of the main repo
ghbot.head_url        // Git URL of the pull request repo
ghbot.head_ref        // Name of pull request branch
ghbot.head_sha        // SHA of the most recent commit in the pull request
ghbot.debug           // True if the server was invoked with --debug
ghbot.octokit         // Octokit instance with access to the bot account
ghbot.repo            // Current repo of the bot

as well as the following methods:

gh-bot.message(str)    // Instruct the bot to write 'str' in the pull request response

Leaving comments as a different user

If you want the bot to leave comments as a different Github user (here are some gravatar suggestions), simply start the server with an auth token of the desired user:

$ gh-bot start

Configuring (config.json)

Here are some important properties you might want to modify:

host              // Host name of server. By default gh-bot will use its public IP
name              // Name of the bot, in case you have multiple ones (e.g. `gh-bot-Windows`, `gh-bot-Linux`, etc)
handles           // Array of handles the bot responds to via `/handle command` (e.g. `['gh-bot', 'gh-bot-linux']`)
whitelist         // Array of Github user names allowed to trigger gh-bot commands via pull request comments
public_dir        // Path to the base directory where all web-facing files should be stored
private_dir       // Path to the base directory where all tests will be run
script_timeout    // (In seconds) Will kill any script that takes longer than this
use_queue         // Set to true if commands should be run in a queue, i.e. not concurrently
                  // (Useful when commands are too memory/CPU heavy, e.g. browser tests)

FAQ

I don't want to use gh-bot anymore. How do I uninstall the Github hooks installed by gh-bot?

On your Github repo, go to Admin > Service Hooks > Post-Receive URLs and disable the URL corresponding to the IP of your machine. (Don't forget to save it).

How does the bot handle security?

gh-bot by default only responds to white-listed users.

How do I get a list of available commands/scripts?

In a pull request discussion, issue:

/gh-bot help