npm’s 2019 JavaScript ecosystem survey analysis is now available!Get your copy here »


2.0.0 • Public • Published


A service to receive github webhook events & run scripts in response. Run custom testing or deploys in response to pushes. Built on top of rvagg's github-webhook-handler and mcavage's restify.

on npm Tests Coverage Dependencies


npm install --save jthoober

Set up jthoober somewhere that github has access to. Create a shared secret for github to send to the webhook & make a note of it. Run jthoober like this:

Usage: jthoober --rules path/to/rules.js --secret sooper-sekrit
  --rules, -r  path to the rules file                         [required]
  --secret     shared secret with github                      [required]
  -p, --port   port to listen on                              [default: 5757]
  -h, --host   host to bind to                                [default: "localhost"]
  --mount      path to mount routes on                        [default: "/webhook"]
  --slack      full url of slack webhook to post results
  --help       Show help

I like to use nginx to terminate tls then proxy pass through to jthoober. I run it under upstart.

Set up a webhook for a project on github. Point it to your jthoober location & give it the secret string you created earlier. Observe that the test payload makes it through.

Optionally, set up an incoming webhook for your Slack organization to report results to a specific channel.


The rules file must export an array of hashes; each hash is passed to the Rule constructor to make an object. (NOTE: I will make this smarter than that before publishing this.) Set up rules that match repos to scripts to execute when jthoober receives an event. Here are some examples:

module.exports =
    { pattern:/jthoober/,
      event: '*',
      script: '/usr/local/bin/fortune'
    { pattern: /request/,
      event: 'push',
      script: './',
    { pattern: /reponame/,
      branchPattern: /master/,
      event: 'push',
      script: './'
      pattern: /reponame/,
      event: 'push',
      script: './example-script.js',
      cmd: 'node',
      args: [process.env, '-t 100']
      // will result in `node ./example-script.js <repoName> <branchName> <env> -t 100`
      pattern: /issue/,
      event: 'issues',
      func: function(event, cb) { console.log('hi'); cb(); },
      pattern: /manyissues/,
      event: 'issues',
      args: [process.env, 'cheddar'],
      func: function(event, env, cheese, cb) { console.log('hi'); cb(); }
      pattern: /customLoggers/,
      event: '*',
      // options to pass to bole.output
      loggers: {level: 'debug', stream: myWritableStream},
      func: function(event, cb){'hi');

Rules may either invoke a script file or call a javascript function.

A javascript function will be passed the event object & a callback to fire when complete.

All rules receive the repo name as the first script argument & the ref of the commit (aka the branch) as the second. If the event is a push event, the third argument is the after payload field, aka the hash of the head commit. If you are passing the event to a javascript function instead of invoking an external script, you are given have the whole event to play with.

Valid rules options:

  • pattern: required; regexp to match against the repo name
  • branchPattern: regexp to match against the branch name.
  • event: required; github event to match on; * matches all events
  • func: javascript function to invoke on match; mutually exclusive with script
  • script: external executable to invoke on match
  • cmd: the executable to run the script with; unused for functions. e.g. bash
  • args: an array of additional args to pass to the script or function. These args come after the repo and branch names, at the end of args passed. If func is passed, these args will come after the event name.
  • slack: an object of slack options to pass to the slack reporter. Only used if --slack is passed.


/webhook - route that responds to the webhook. Configurable; pass --mount /foo to the runner to mount the handler on /foo instead.

/ping - responds with 200 "OK". Use this to monitor.


The server logs events & status in json to stdout. Pipe the output through bistre --time to get pretty logs.


j'thoob is the official pronunciation of gi-thub, aka the site this code is hosted on.


Pass more stuff from the hook event to the bash script. Commit hash? Why not allow rules to be arbitrary node code? Or just define a handler API? But bash is so handy.

Logging for js functions?


ISC; see the LICENSE file.


npm i jthoober

Downloadsweekly downloads









last publish


  • avatar
  • avatar
  • avatar
Report a vulnerability