gith
Version: 1.0.4
gith[ooks] - 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 9001var gith = ;
Use
Pass an object of how you want to filter gith (if at all) and subscribe to an event.
;
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:
;
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
Note that this payload will only be fully available in case of standard push
hooks (see below for more information).
gith()
The gith function returns a new Gith object that has all of the EventEmitter2 methods.
gith
Methods
Additional 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.
gith
for other types of hooks
Using When you use Github UI to declare a web hook, it's only attached to the push
event.
Whenever you want to attach you hook to other events, you will have to use the API. In this case, gith
may not be able to fully interpret the original payload, and you should consider the simplified payload as unreliable. In those cases, just use payload.original
.
License
Copyright (c) 2012 Dan Heberden Licensed under the MIT license.