Flask webhook for Github

A very simple github post-receive web hook handler that executes per default a pull uppon receiving. The executed action is configurable per repository.

It will also verify that the POST request originated from github.com or a defined GitHub Enterprise server. Additionally will ensure that it has a valid signature (only when the key setting is properly configured).

Gettings started

Installation Requirements

Install dependencies found in requirements.txt.

pip install -r requirements.txt

Repository Configuration

Edit repos.json to configure repositories, each repository must be registered under the form GITHUB_USER/REPOSITORY_NAME.

{
    "razius/puppet": {
        "path": "/home/puppet",
        "key": "MyVerySecretKey",
        "action": [["git", "pull", "origin", "master"] ],
    },
    "d3non/somerandomexample/branch:live": {
        "path": "/home/exampleapp",
        "key": "MyVerySecretKey",
        "action": [["git", "pull", "origin", "live"],
            ["echo", "execute", "some", "commands", "..."] ]
    }
}

Runtime Configuration

Runtime operation is influenced by a set of environment variables which require being set to influence operation. Only FLASK_GITHUB_WEBHOOK_REPOS_JSON is required to be set, as this is required to know how to act on actions from repositories. The remaining variables are optional. USE_PROXYFIX needs to be set to true if being used behind a WSGI proxy, and is not required otherwise. GHE_ADDRESS needs to be set to the IP address of a GitHub Enterprise instance if that is the source of webhooks.

Set environment variable for the repos.json config.

export FLASK_GITHUB_WEBHOOK_REPOS_JSON=/path/to/repos.json

Start the server.

python index.py 80

Start the server behind a proxy (see: http://flask.pocoo.org/docs/deploying/wsgi-standalone/#proxy-setups)

USE_PROXYFIX=true python index.py 8080

Start the server to be used with a GitHub Enterprise instance.

GHE_ADDRESS=192.0.2.50 python index.py 80

Go to your repository's settings on github.com or your GitHub Enterprise instance and register your public URL under Service Hooks -> WebHook URLs.

Tips & Tricks

If you want to use this with a tunneling service, ngrok for example, you will need to set a GHE_ADDRESS for 127.0.0.1 to allow the tunnel to post.

kgleason / github-webhook-handler