jthoober

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.

Usage

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

Options:
  --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.

Rules

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: './example-script.sh',
      passargs: true
    },
    { pattern: /reponame/,
      branchPattern: /master/,
      event: 'push',
      script: './example-script.sh'
    },
    {
      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){
        this.logger.info('hi');
        cb();
      }
    }
];

Rules may either invoke a script file or call a javascript function. The function will be passed the event object & a callback to fire when complete.

Rules with passargs set will receive the repo name as the first script argument & the ref of the commit (aka the branch) as the second. This option is meaningless if you are passing a javascript function instead of invoking an external script. (You have the whole event to play with in that case.)

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
• passargs: if set & truthy, repo name & branch are sent to executable
• logfile: full path of file to log executable output to; unused for functions
• cmd: the executable to run the script with; unused for functions. e.g. node
• args: an array of additional args to pass to the script or function. If parseargs is true these args will come after the repo and branch names. 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.

Endpoints

/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.

Logging

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

Notes

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

TODO

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?

License

ISC; see the LICENSE file.