├── .gitignore
├── .jshintignore
├── .jshintrc
├── LICENSE
├── README.md
├── bin
    └── githubhook
├── index.js
└── package.json


/.gitignore:
--------------------------------------------------------------------------------
1 | .swp
2 | node_modules
3 | 


--------------------------------------------------------------------------------
/.jshintignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | 


--------------------------------------------------------------------------------
/.jshintrc:
--------------------------------------------------------------------------------
 1 | {
 2 |   "node": true,
 3 | 
 4 |   "curly": true,
 5 |   "latedef": true,
 6 |   "quotmark": true,
 7 |   "undef": true,
 8 |   "unused": true,
 9 |   "trailing": true
10 | }
11 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | Programmed by Nathan LaFreniere, Copyright (c) 2012 &Yet
 2 | 
 3 | Permission is hereby granted, free of charge, to any person obtaining a copy
 4 | of this software and associated documentation files (the "Software"), to deal
 5 | in the Software without restriction, including without limitation the rights
 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 7 | copies of the Software, and to permit persons to whom the Software is
 8 | furnished to do so, subject to the following conditions:
 9 | 
10 | The above copyright notice and this permission notice shall be included in
11 | all copies or substantial portions of the Software.
12 | 
13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19 | THE SOFTWARE.
20 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | node-github-hook
  2 | ================
  3 | 
  4 | This is a very simple, easy to use evented web hook API for GitHub or GitLab. A command-line executable is also available.
  5 | 
  6 | To Install:
  7 | -----------
  8 | ```
  9 | npm install githubhook
 10 | ```
 11 | 
 12 | To Use:
 13 | -------
 14 | 
 15 | ```javascript
 16 | var githubhook = require('githubhook');
 17 | var github = githubhook({/* options */});
 18 | 
 19 | github.listen();
 20 | 
 21 | github.on('*', function (event, repo, ref, data) {
 22 | });
 23 | 
 24 | github.on('event', function (repo, ref, data) {
 25 | });
 26 | 
 27 | github.on('event:reponame', function (ref, data) {
 28 | });
 29 | 
 30 | github.on('event:reponame:ref', function (data) {
 31 | });
 32 | 
 33 | github.on('reponame', function (event, ref, data) {
 34 | });
 35 | 
 36 | github.on('reponame:ref', function (event, data) {
 37 | });
 38 | 
 39 | // GitLab system hooks
 40 | github.on('*', function (event, type, data) {
 41 | });
 42 | 
 43 | github.on('type', function (event, data) {
 44 | });
 45 | 
 46 | // if you'd like to programmatically stop listening
 47 | // github.stop();
 48 | ```
 49 | 
 50 | Where 'event' is the event name to listen to (sent by GitHub or Gitlab, typically 'push' or 'system'), 'reponame' is the name of your repo (this one is node-github-hook), 'ref' is the git reference (such as ref/heads/master), and 'type' is the type of system hook.
 51 | 
 52 | Configure a WebHook URL to whereever the server is listening, with a path of ```/github/callback``` and you're done!
 53 | 
 54 | Available options are:
 55 | 
 56 | * **host**: the host to listen on, defaults to '0.0.0.0'
 57 | * **port**: the port to listen on, defaults to 3420
 58 | * **path**: the path for the GitHub callback, defaults to '/github/callback'
 59 | * **wildcard**: if true, the path for the GitHub callback will be considered valid as long as it *starts* with the configured path
 60 | * **secret**: if specified, you must use the same secret in your webhook configuration in GitHub. if a secret is specified, but one is not configured in GitHub, the hook will fail. if a secret is *not* specified, but one *is* configured in GitHub, the signature will not be validated and will be assumed to be correct. consider yourself warned. this option can also be a function that takes the following parameters: (request, data, callback). callback is error first and should be passed (err, secret)
 61 | * **logger**: an optional instance of a logger that supports the "log" and "error" methods and one parameter for data (like console), default is `console`.
 62 | * **https**: Options to pass to nodejs https server. If specified, you must follow documentation about nodejs https library (See options in https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener)
 63 | * **trustProxy**: By default the `x-forwarded-for` header is trusted when determining the remoteAddress to log for a request. Set this to `false` to disable this behavior
 64 | * **enableHealthcheck**: Respond to GET requests with a 204 response for healthcheck purposes
 65 | * **healthcheckCode**: Override the 204 status code for healthchecks (for systems that aren't friendly with HTTP spec compliance and want a 200, for example)
 66 | 
 67 | 
 68 | Command-line
 69 | -------------
 70 | 
 71 | You can use the command-line client to execute a shell script when a particular
 72 | event occurs.
 73 | 
 74 | Install it globally:
 75 | 
 76 | ```bash
 77 | $ npm install -g githubhook
 78 | ```
 79 | 
 80 | Then you can run `githubhook`:
 81 | 
 82 | ```bash
 83 | $ githubhook --help
 84 | 
 85 | Usage:
 86 |   githubhook [--host=HOST] [--port=PORT] [--callback=URL_PATH] [--secret=SECRET] [--verbose] <trigger> <script>
 87 | 
 88 | Options:
 89 | 
 90 |   --host=HOST             Address to listen on
 91 |   --port=PORT             Port to listen on
 92 |   --callback=URL_PATH     The callback URL path
 93 |   --secret=SECRET         The secret you use the in the GitHub webhook config
 94 |   --key=KEY_PATH          Path to read https certificate key file
 95 |   --cert=CERT_PATH        Path to read https certificate file
 96 |   --verbose               Log to console
 97 |   --version               Output the version number
 98 |   -h, --help              Output usage information
 99 | ```
100 | 
101 | Default values for options are same as for the API (see above).
102 | 
103 | Example usage:
104 | 
105 | ```bash
106 | $ githubhook push:node-github-hook ./some_script.sh
107 | ```
108 | 
109 | 
110 | License
111 | =======
112 | 
113 | MIT
114 | 


--------------------------------------------------------------------------------
/bin/githubhook:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env node
 2 | 
 3 | var child_process = require('child_process'),
 4 |   docopt = require('docopt'),
 5 |   multiline = require('multiline'),
 6 |   fs = require('fs'),
 7 |   path = require('path');
 8 | 
 9 | var githubhook = require('../');
10 | 
11 | 
12 | var doc = multiline(function() {/*
13 | 
14 | Usage:
15 |   githubhook [--host=HOST] [--port=PORT] [--callback=URL_PATH] [--secret=SECRET] [--key=KEY_PATH] [--cert=CERT_PATH] [--verbose] <trigger> <script>
16 | 
17 | Options:
18 | 
19 |   --host=HOST             Address to listen on
20 |   --port=PORT             Port to listen on
21 |   --callback=URL_PATH     The callback URL path
22 |   --secret=SECRET         The secret you use the in the Github webhook config
23 |   --key=KEY_PATH          Path to read https certificate key file
24 |   --cert=CERT_PATH        Path to read https certificate file
25 |   --verbose                 Log to console
26 |   --version                 Output the version number
27 |   -h, --help                Output usage information
28 | 
29 | */});
30 | 
31 | 
32 | var options = docopt.docopt(doc, {
33 |   version: require('../package.json').version,
34 |   help: true,
35 |   options_first: false,
36 |   exit: true
37 | });
38 | 
39 | var githubhookConfig = {
40 |   host: options['--host'],
41 |   port: options['--port'] ? parseInt(options['--port']) : null,
42 |   path: options['--callback'],
43 |   secret: options['--secret'],
44 |   logger: options['--verbose'] ? console : null
45 | };
46 | 
47 | if (options['--cert']) {
48 |   githubhookConfig.https = {
49 |     key: fs.readFileSync(options['--key']),
50 |     cert: fs.readFileSync(options['--cert'])
51 |   }
52 | }
53 | 
54 | var github = githubhook(githubhookConfig);
55 | 
56 | // start it!
57 | github.listen();
58 | 
59 | // trigger
60 | github.on(options['<trigger>'], function () {
61 |   var scriptPath = path.resolve(options['<script>']);
62 |   var spawnOptions = {};
63 |   var verbose = options['--verbose'];
64 | 
65 |   var data = Array.prototype.slice.call(arguments).pop();
66 |   var repo = (data && data.repository && data.repository.name) ? data.repository.name : '';
67 |   var ref = (data && data.ref) ? data.ref : '';
68 |   
69 |   if (verbose) {
70 |     console.log('--> EXEC', scriptPath, repo, ref);
71 |     spawnOptions.stdio = 'inherit';
72 |   }
73 | 
74 |   var child = child_process.spawn(scriptPath, [repo, ref], spawnOptions);
75 |   if (verbose) {
76 |     child.on('error', function (err) {
77 |       console.error(err.stack);
78 |     });
79 | 
80 |     child.on('close', function () {
81 |       console.log('--- END', scriptPath);
82 |     });
83 |   }
84 | });
85 | 


--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
  1 | var Http = require('http');
  2 | var Https = require('https');
  3 | var Url = require('url');
  4 | var Querystring = require('querystring');
  5 | var EventEmitter = require('events').EventEmitter;
  6 | var Util = require('util');
  7 | var Crypto = require('crypto');
  8 | 
  9 | function reply(statusCode, res) {
 10 | 
 11 |     var message = { message: Http.STATUS_CODES[statusCode].toLowerCase() };
 12 |     message.result = statusCode >= 400 ? 'error' : 'ok';
 13 |     message = JSON.stringify(message);
 14 | 
 15 |     var headers = {
 16 |         'Content-Type': 'application/json',
 17 |         'Content-Length': message.length
 18 |     };
 19 | 
 20 |     res.writeHead(statusCode, headers);
 21 |     res.end(message);
 22 | }
 23 | 
 24 | function parse(data) {
 25 | 
 26 |     var result;
 27 |     try {
 28 |         result = JSON.parse(data);
 29 |     } catch (e) {
 30 |         result = false;
 31 |     }
 32 |     return result;
 33 | }
 34 | 
 35 | function serverHandler(req, res) {
 36 | 
 37 |     var self = this;
 38 |     var url = Url.parse(req.url, true);
 39 |     var buffer = [];
 40 |     var bufferLength = 0;
 41 |     var failed = false;
 42 |     var isForm = false;
 43 |     var remoteAddress;
 44 |     if (this.trustProxy !== false) {
 45 |       remoteAddress = req.headers['x-forwarded-for'];
 46 |     }
 47 |     remoteAddress = remoteAddress || req.ip || req.socket.remoteAddress || req.socket.socket.remoteAddress;
 48 | 
 49 |     req.on('data', function (chunk) {
 50 | 
 51 |         if (failed) {
 52 |             return;
 53 |         }
 54 | 
 55 |         buffer.push(chunk);
 56 |         bufferLength += chunk.length;
 57 |     });
 58 | 
 59 |     req.on('end', function (chunk) {
 60 | 
 61 |         if (failed) {
 62 |             return;
 63 |         }
 64 | 
 65 |         var data;
 66 | 
 67 |         if (chunk) {
 68 |             buffer.push(chunk);
 69 |             bufferLength += chunk.length;
 70 |         }
 71 | 
 72 | 
 73 |         self.logger.log(Util.format('received %d bytes from %s', bufferLength, remoteAddress));
 74 |         var event = req.headers['x-github-event'] || req.headers['x-gogs-event'] || req.headers['x-event-key'] || (req.headers['x-gitlab-event'] ? req.headers['x-gitlab-event'].split(' ')[0].toLowerCase() : 'unknown');
 75 |         if (event === 'ping') {
 76 |             self.emit(event, null, null, data);
 77 |             return reply(200, res);
 78 |         }
 79 | 
 80 |         if (req.headers['content-type'] === 'application/x-www-form-urlencoded') {
 81 |             isForm = true;
 82 |             data = Buffer.concat(buffer, bufferLength).toString();
 83 |         } else {
 84 |             //this is already a string when sent as JSON
 85 |             data = Buffer.concat(buffer, bufferLength);
 86 |         }
 87 | 
 88 |         self.getSecret(req, function (err, secret) {
 89 | 
 90 |             if (err) {
 91 |                 self.logger.error(Util.format('error getting secret for %s, returning 403',  res.url));
 92 |                 self.logger.error(err.stack);
 93 |                 return reply(403, res);
 94 |             }
 95 | 
 96 |             if (secret) {
 97 |                 var signature = req.headers['x-hub-signature'];
 98 | 
 99 |                 if (!signature) {
100 |                     self.logger.error('secret configured, but missing signature, returning 403');
101 |                     return reply(403, res);
102 |                 }
103 | 
104 |                 signature = signature.replace(/^sha1=/, '');
105 |                 var digest = Crypto.createHmac('sha1', secret).update(data).digest('hex');
106 | 
107 |                 if (signature !== digest) {
108 |                     self.logger.error('got invalid signature, returning 403');
109 |                     return reply(403, res);
110 |                 }
111 |             }
112 | 
113 |             if (isForm) {
114 |                 data = Querystring.parse(data).payload;
115 |             }
116 |             data = parse(data);
117 | 
118 | 
119 |             // invalid json
120 |             if (!data) {
121 |                 self.logger.error(Util.format('received invalid data from %s, returning 400', remoteAddress));
122 |                 return reply(400, res);
123 |             }
124 | 
125 |             data.request = req;
126 | 
127 |             // handle GitLab system hook
128 |             if (event !== 'system'){
129 |                 // invalid json
130 |                 if (!data.repository || !data.repository.name) {
131 |                     self.logger.error(Util.format('received incomplete data from %s, returning 400', remoteAddress));
132 |                     return reply(400, res);
133 |                 }
134 | 
135 |                 var repo = data.repository.name;
136 |                 var ref = data.ref;
137 | 
138 |                 // and now we emit a bunch of data
139 |                 if (ref) {
140 |                     self.logger.log(Util.format('got %s event on %s:%s from %s', event, repo, ref, remoteAddress));
141 |                 }
142 |                 else {
143 |                     self.logger.log(Util.format('got %s event on %s from %s', event, repo, remoteAddress));
144 |                 }
145 |                 self.emit('*', event, repo, ref, data);
146 |                 self.emit(repo, event, ref, data);
147 |                 self.emit(repo + ':' + ref, event, data);
148 |                 self.emit(event, repo, ref, data);
149 |                 self.emit(event + ':' + repo, ref, data);
150 |                 self.emit(event + ':' + repo + ':' + ref, data);
151 |             } else {
152 |                 var type = data.event_name;
153 | 
154 |                 // invalid json
155 |                 if (!type) {
156 |                     self.logger.error(Util.format('received incomplete data from %s, returning 400', remoteAddress));
157 |                     return reply(400, res);
158 |                 }
159 | 
160 |                 self.logger.log(Util.format('got %s event of type %s from %s', event, type, remoteAddress));
161 | 
162 |                 // and now we emit a bunch of data
163 |                 self.emit('*', event, type, data);
164 |                 self.emit(type, event, data);
165 |             }
166 | 
167 |             reply(200, res);
168 |         });
169 |     });
170 | 
171 |     self.logger.log(Util.format(req.method, req.url, remoteAddress));
172 | 
173 |     // 404 if the path is wrong
174 |     if (!self.checkUrl(url)) {
175 |         self.logger.error(Util.format('got invalid path from %s, returning 404', remoteAddress));
176 |         failed = true;
177 |         return reply(404, res);
178 |     }
179 | 
180 |     // 204 if healthchecks are enabled and it's a GET
181 |     // note that we flag the request as failed only to
182 |     // stop processing any further incoming request data
183 |     if (req.method === 'GET' && this.enableHealthcheck) {
184 |         failed = true;
185 |         return reply(this.healthcheckCode, res);
186 |     }
187 | 
188 |     // 405 if the method is wrong
189 |     if (req.method !== 'POST') {
190 |         self.logger.error(Util.format('got invalid method from %s, returning 405', remoteAddress));
191 |         failed = true;
192 |         return reply(405, res);
193 |     }
194 | 
195 |     // 400 if it's not a github, gitlab, or bitbucket event
196 |     if (!req.headers.hasOwnProperty('x-github-event') && !req.headers.hasOwnProperty('x-gitlab-event') && !req.headers.hasOwnProperty('x-gogs-event') && !req.headers.hasOwnProperty('x-event-key')) {
197 |         self.logger.error(Util.format('missing x-github-event, x-gitlab-event, x-gogs-event, or x-event-key header from %s, returning 400', remoteAddress));
198 |         failed = true;
199 |         return reply(400, res);
200 |     }
201 | }
202 | 
203 | var GithubHook = function (options) {
204 | 
205 |     if (!(this instanceof GithubHook)) {
206 |         return new GithubHook(options);
207 |     }
208 | 
209 |     options = options || {};
210 |     this.port = options.port || 3420;
211 |     this.host = options.host || '0.0.0.0';
212 |     this.secret = options.secret || false;
213 |     this.logger = options.logger || console;
214 |     this.path = options.path || '/github/callback';
215 |     this.wildcard = options.wildcard || false;
216 |     this.trustProxy = options.trustProxy || false;
217 |     this.enableHealthcheck = options.enableHealthcheck || false;
218 |     this.healthcheckCode = options.healthcheckCode || 204;
219 | 
220 |     if (options.https) {
221 |       this.server = Https.createServer(options.https, serverHandler.bind(this));
222 |     }
223 |     else {
224 |       this.server = Http.createServer(serverHandler.bind(this));
225 |     }
226 | 
227 |     EventEmitter.call(this);
228 | };
229 | 
230 | Util.inherits(GithubHook, EventEmitter);
231 | 
232 | GithubHook.prototype.listen = function (callback) {
233 | 
234 |     var self = this;
235 | 
236 |     self.server.listen(self.port, self.host, function () {
237 | 
238 |         self.logger.log(Util.format('listening for hook events on %s:%d', self.host, self.port));
239 | 
240 |         if (typeof callback === 'function') {
241 |             callback();
242 |         }
243 |     });
244 | };
245 | 
246 | 
247 | GithubHook.prototype.checkUrl = function (url) {
248 | 
249 |     if (url.pathname === this.path) {
250 |         return true;
251 |     }
252 | 
253 |     if (this.wildcard && (url.pathname.indexOf(this.path + '/') === 0)) {
254 |         return true;
255 |     }
256 | 
257 |     return false;
258 | };
259 | 
260 | GithubHook.prototype.stop = function (callback) {
261 | 
262 |     var self = this;
263 | 
264 |     self.server.close(function () {
265 | 
266 |         self.logger.log('stopped listening for github events');
267 |         self.server = Http.createServer(serverHandler.bind(this));
268 | 
269 |         if (typeof callback === 'function') {
270 |             callback();
271 |         }
272 |     });
273 | };
274 | 
275 | GithubHook.prototype.getSecret = function (req, next) {
276 | 
277 |     if (typeof this.secret === 'function') {
278 |         return this.secret(req, next);
279 |     }
280 |     return next(null, this.secret);
281 | };
282 | 
283 | module.exports = GithubHook;
284 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "githubhook",
 3 |   "description": "a simple github post-receive hook",
 4 |   "author": "Nathan LaFreniere",
 5 |   "version": "1.9.3",
 6 |   "main": "./index.js",
 7 |   "repository": "git://github.com/nlf/node-github-hook.git",
 8 |   "devDependencies": {
 9 |     "jshint": "^2.5.1",
10 |     "precommit-hook": "^1.0.2"
11 |   },
12 |   "dependencies": {
13 |     "docopt": "^0.6.2",
14 |     "multiline": "^1.0.2"
15 |   },
16 |   "bin": {
17 |     "githubhook": "./bin/githubhook"
18 |   }
19 | }
20 | 


--------------------------------------------------------------------------------