githooked
A GitHub webhooks worker!
githooked is a tiny library and companion CLI tool for handling GitHub webhooks hooks. This repo is a fork of https://github.com/coreh/hookshot and was created since the author of hookshot was innactive.
When setting up webhooks in your githooked dashboard, the types of events that should be sent to githooked should be set to: 'Just the push event'
Examples
Library
var githooked = ;
CLI Tool
githooked -r refs/heads/master 'git pull && make'
Usage
The library exposes a single function, githooked()
. When called, this functions returns an express instance configured to handle webhooks pushes 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 githooked()
function.
Arguments
GitHooked supports up to three arguments: reference, action, and options. The first argument is the branch reference from the GitHooked webhook (i.e: refs/heads/master
). If only one argument is supplied, it should be the action that needs to be ran. In this instance githooked will bind to every webhook event sent from GitHub.
;
Reference
References are specific webhook references or actions fired when editing tags or branches changes happen. This argument is provided so you can bind to specific branch or the following event hooks:
- hook: This will bind to all webhooks
- create: fired on create events
- delete: fired on delete events
- push: fired on push events
Action
Actions can either be shell commands or JavaScript functions.
Options
Lastly, the third option is an object of configuration parameters. Usage:
The following configuration options are:
json (Object)
These are arguments passed to express's body-parsers json() middleware
middleware (Function|Array[Function])
This is an array or function of valid express middleware. This middleware will be applied before any other express middleware. If an array is provided, the middleware will be applied in the order they are declared in the array.
secret (String)
GitHub webhooks can pass a secret which is used as an validation mechanism between your GitHub repo and your githooked server. Read more about it here. Validation of the payload will be the first operation performed on incoming requests. If using githooked for any serious purposes this option should be necessary. If validation failed an error event will be called with value of 'signature validation failed' or 'no provider signature':
githooked
logFile (String|stream) TODO
If your action is a shell call, then this option will log all STDOUT and STDERR into the provided stream or file descriptor
Mounting to existing express servers
githooked can be mounted to a custom route on your existing express server:
// ...app;// ...
Special Events
Special events are fired when branches/tags are created, deleted:
The push
event is fired when a push is made to any ref:
Finally, the hook
event is fired for every post-receive hook that is send by GitHub.
Spawn Event
If githooked was created with a shell command as the action, it will throw a spawn event with the child_process spawn instance.
var server = ; server;
CLI Tool
A companion CLI tool is provided for convenience. To use it, install githooked via npm using the -g
flag:
npm install -g githooked
The CLI tool takes as argument a command to execute upon GitHub post-receive hook:
githooked '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):
githooked -r refs/heads/master -p 9001 'echo "pushed to master!"'