README.md

hookshot

"You found the hookshot! It's a spring-loaded chain that you can cast out to hook things."

Intro

hookshot is a tiny library and companion CLI tool for handling GitHub post-receive hooks.

Examples

Library

var hookshot = require('hookshot');
hookshot('refs/heads/master', 'git pull && make').listen(3000)

CLI Tool

hookshot -r refs/heads/master 'git pull && make'

Usage

The library exposes a single function, hookshot(). When called, this functions returns an express instance configured to handle post-receive hooks from GitHub. You can react to pushes to specific branches by listening to specific events on the returned instance, or by providing optional arguments to the hookshot() function.

hookshot()
.on('refs/heads/master', 'git pull && make')
.listen(3000)

hookshot('refs/heads/master', 'git pull && make').listen(3000)

Actions

Actions can either be shell commands or JavaScript functions.

hookshot('refs/heads/master', 'git pull && make').listen(3000)

hookshot('refs/heads/master', function(info) {
  // do something with push info ...
}).listen(3000)

Mounting to existing express servers

hookshot can be mounted to a custom route on your existing express server:

// ...
app.use('/my-github-hook', hookshot('refs/heads/master', 'git pull && make'));
// ...

Special Events

Special events are fired when branches/tags are created, deleted:

hookshot()
.on('create', function(info) {
  console.log('ref ' + info.ref + ' was created.')
})
.on('delete', function(info) {
  console.log('ref ' + info.ref + ' was deleted.')
})

The push event is fired when a push is made to any ref:

hookshot()
.on('push', function(info) {
  console.log('ref ' + info.ref + ' was pushed.')
})

Finally, the hook event is fired for every post-receive hook that is send by GitHub.

hookshot()
.on('push', function(info) {
  console.log('ref ' + info.ref + ' was pushed.')
})

CLI Tool

A companion CLI tool is provided for convenience. To use it, install hookshot via npm using the -g flag:

npm install -g hookshot

The CLI tool takes as argument a command to execute upon GitHub post-receive hook:

hookshot 'echo "PUSHED!"'

You can optionally specify an HTTP port via the -p flag (defaults to 3000) and a ref via the -r flag (defaults to all refs):

hookshot -r refs/heads/master -p 9001 'echo "pushed to master!"'