hookshot

hookshot

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

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

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

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 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)

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 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.')
})

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!"'