gith v1.0.4
gith
githooks - a simple node server that responds to github post-receive events with meaningful data
Getting Started
Install
Install the module with: npm install gith
Require
In your node application, require gith and create a gith server. You can specify a port now, or
you can use the .listen( portNumber )
method later.
// create a gith server on port 9001
var gith = require('gith').create( 9001 );
Use
Pass an object of how you want to filter gith (if at all) and subscribe to an event.
gith({
repo: 'danheberden/gith'
}).on( 'all', function( payload ) {
console.log( 'Post-receive happened!' );
});
Hook
Be sure github.com is sending payload data to your server. From your repository root
go to Admin > Service Hooks > WebHook URLs
and add your server url, e.g., http://mycoolserver.com:9001
.
Filtering
The object passed into gith()
can utilize four parameters (repo
, branch
, file
and tag
).
All of these can either be an exact match string, a regular expression or a function.
For example:
gith({
repo: 'danheberden/gith',
branch: /issue_(\d+)/
}).on( 'branch:add', function( payload ) {
console.log( 'A branch matching /issue_(\d+)/ was added!' );
console.log( 'The issue # is', payload.matches.branch[1] );
});
You can either omit the key that you don't want to filter (e.g., we would get every file and tag in the above
example) or use *
to specifiy that it's a wildcard.
Events
Events available are:
all
- as long as the filtering passed, this will get firedbranch:add
branch:delete
file:add
file:modify
file:delete
file:all
tag:add
tag:delete
Payload
The github payload is very detailed, but can be a bit excessive.
This is the payload that gith gives you:
{
original: the-original-github-payload,
files: {
all: [],
added: [],
deleted: [],
modified: []
},
tag: tag, /* if a tagging operation */
branch: branch, /* if working on a branch */
repo: the-repo-name,
sha: the-now-current-sha,
time: when-it-was-pushed,
urls: {
head: current-sha
branch: branch-url-if-available,
tag: sha-url-of-tag-if-available,
repo: repo-url,
compare: compare-url
},
reset: did-the-head-get-reset,
pusher: github-username-of-pusher,
owner: github-username-of-repo-owner
}
gith()
The gith function returns a new Gith object that has all of the EventEmitter2 methods.
Additional gith
Methods
On the gith server, there are three additional methods available:
gith.close()
This closes the gith server
gith.listen( port )
If you didn't pass in a port to .create()
when you required gith, this
will start the server on the specified port
gith.payload( github-style-payload )
You can broadcast a payload to the gith server manually.
License
Copyright (c) 2012 Dan Heberden Licensed under the MIT license.