Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
simple node server that responds to github post-receive events with meaningful data
JavaScript
branch: master

expose gith.ips array of valid ips to allow requests from; populated …

…with default github post-receive ips. Closes issue #13
latest commit e5e2d5cb09
Dan Heberden authored

README.md

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 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 fired
  • branch: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.

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.

Using gith for other types of hooks

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.

Something went wrong with that request. Please try again.