Awesome Open Source
Awesome Open Source

git-webhook-ci NPM version Build Status Dependency Status

A Git (github/gitee) webhook callback server to fetch new code (poor man CI)

This little tool is born out of real projects. Keep having to deploy and setup demo site etc. Why bother if you own the git account? You just need a new cert from github, add this to your project, and setup accordingly, and Viola, you get your own poor man CI :)


  $ npm install --save git-webhook-ci


  $ yarn add git-webhook-ci

Configuration and usage

Create a js file (normally on your project root directory). Let's call it webhook.js.

const gitWebhook = require('git-webhook-ci');
const config = {
  "secret": "your-github-webhook-secret",
  "path": "/webhook",
  "port": 8081,
  "branch": "refs/heads/master", // New in 0.4.1 you can pass * wildcard to listen to all branches
  "cmd": "git pull origin master --no-edit"


The minimum setup can be like this:

  // Default is github
  gitWebhook({secret: "your-github-webhook-secret"});

  // For Gitee
  gitWebhook({secret: 'your-gitee-password', provider: 'gitee'});

  // For Gitlab
  gitWebhook({secret: 'your-gitlab-token', provider: 'gitlab'});

New in 0.4.0 - cmd accept (String) command to run or (Function) callback

The cmd config option now accept a function.

The signature as follow

  secret: 'your-secret-between-you-and-github',
  cmd: (result, opt, ref) => {
    // result has 3 properties
    // 1. payload
    // 2. host
    // 3. event - from github / gitee
    // opt is an environment variable that you can pass to the spawn

Example how to combine the wildcard branch option, and a function callback

const gitWebhook = require('git-webook-ci');
const { spawn } = require('child_process');

const server = gitWebhook({
  secret: 'your-secret-between-you-and-github',
  branch: '*',
  cmd: (result, opt, ref) => {
    switch (ref) {
      case 'refs/heads/master':
        const e1 = spawn('npm', ['run', 'something'], opt);
      case 'refs/heads/develop':
        const e2 = spawn('npm', ['run', 'something-else'], opt);
        // do special stuff using the result object
        specialFunc(result.payload, opt);

As you can see from the code example from above. The method gitWebhook actually return the server instance from http.createServer. So you can make it to stop, restart etc easily.

New in 0.4.x - support 码云

You can now pass a new configuration option provider:

  secret: 'your-password-between-you-and-gitee',
  provider: 'gitee'

New in 0.5.x - support

You just need to change the provider to gitlab:

  secret: 'your-gitlab-token',
  provider: 'gitlab'

New in 0.8.x - support 微信小程序消息服务 Wechat mini app callback

We have added a new provider here - it's not a git repo. It supports the Wechat callback.

There are several different between wechat callback and the other providers

There is a new property that you need to supply when you init your webhook with Wechat. Because this is a two step process. Once your server is verify with Wechat server. They will just push data over to the url. So you need to run this once like so.

First you need to run with the inited:false (default)

  secret: 'the-token-you-setup-with-wechat',
  provider: 'wechat',
  inited: false // this is default

Then re-config your webhook to run normal operation:

  secret: 'the-token-you-setup-with-wechat',
  provider: 'wechat',
  inited: true // default: false

There is a complete example in the wiki to demonstrate how you can do this automatically, with additional module fs-extra, nodemon and node-config.

If you are using function as your cmd property, there will only be two parameters supply, when execute your callback.

    cmd: (result, opt) => {
      // there is no ref

Full configuration properties

Property name Description Default Type
dir Where the git root directory is, default to where it gets call process.cwd() String
secret A secret key pass to encrypt data between github and your server '' String
path The path where the web hook call to your server /webhook String
port The port number where this callback server running on 8081 Integer
branch The branch where you will trigger action when received event from github. You can pass * wildcard to listen to all the branches refs/heads/master String
cmd The command to execute when callback happens. You can also pass this as a function (see above for signature) and especially useful when you use * for branch git pull origin master --no-edit String
inited only available with wechat provider false Boolean

Debug option

Internally we use debug to track what's going on. So you can just pass the env during the start up of the script to debug your setup.

  DEBUG=* node ./webhook.js

If you do that, you will see a huge amount of info. All our debug flags are prefixed with git-webhook-ci, and here is the list of all the keys we use in this npm.

  • git-webhook-ci:main
  • git-webhook-ci:gitlab
  • git-webhook-ci:github
  • git-webhook-ci:gitee
  • git-webhook-ci:wechat
  • git-webhook-ci:demo (only in test)
  • git-webhook-ci:test

For example:

  DEBUG=git-webhook-ci:main,git-webhook-ci:wechat node ./webhook.js

Then you will only see the main (top interface) and the Wechat internal debug messages.


You can install this tools globally.

  $ npm install git-webhook-ci --global

Then you can call it from command line like so

  $ git-webhook-ci /path/to/your/git --secret secret-you-setup

Or in your package.json

    "scripts": {
      "webhook": "git-webhook-ci ./ --secret secret-you-setup"

Then just run it with npm run webhook


Check our Wiki for more information about how to setup your app.



Power by generator-nodex.

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,048,460
Github (43,698
String (42,476
Git (34,433
Provider (15,629
Ci (12,567
Webhook (8,921
Gitlab (5,560
Wechat (4,251
Wechat Mini Program (397
Gitee (36