loganbibby / git-triggler

Nano web hook service for handling Git triggers

git-triggler

Nano web hook service for handling Git triggers

Installation

1. Clone this repo to the server handling the trigger.
2. Create a virtual environment, activate it, and install the dependencies (pip install -r requirements.txt).
3. Create the configuration file.
4. Deploy using gunicorn (gunicorn -w 1 -b 0.0.0.0:5000 server:app)!
5. Open your server's firewall to the server's port (5000 in the example above).

Now your server is ready to accept requests generated by a trigger.

Using with AWS CodeCommit

This project started as a way to handle AWS CodeCommit triggers.

1. In your AWS Console, go to Lambda.
2. Click on the orange "Create function" button.
3. In the "Create function" wizard, click on the orange "Author from scratch" button.
4. Name the function and select or create a role. Click on "Create function" at the bottom.
5. Under "Configuration":
6. Runtime: select "Python 2.7"
7. Handler: type "index.handler"
8. Paste the content of lambda.py into the inline editor.
9. Configure the TRIGGERS dictionary.
10. Under "Triggers":
11. Click "Add trigger".
12. Click the gray dashed box and select "CodeCommit".
13. Select your repository, name the trigger, select events, and select branches. Click "Submit" at the bottom.
14. Add another trigger, if you want. Make sure
15. Click the orange "Save" button at the top.

Using with GitHub

Right now, the server doesn't work with Github Webhooks. :( It's definitely a to-do for the future.

Generating a Hook

The server works by accepting web hooks generated by a Git trigger. They're called webhooks but it's a simple HTTP request. For the server to accept your hook and perform the configured action, the HTTP request must include information to help the server validate who you are and ensure this isn't some random request.

• The repo key is the concatination of your repo name and the branch with a dash inbetween (like git-triggler-master).
• The token is a random string shared between the server and the webhook generator.
• X-Signature-Timestamp is the UNIX epoch timestamp at the time of the request.
• X-Signature is a hash of the concatination of the timestamp, repo key, and token with a colon (:) inbetween (like 123456789:git-triggler-master:s3c43t70k3n). The hash is generated using SHA-256 and the configured number of iterations.

The timestamp expires after a configured number of seconds and can't be any more futuristic than the configured amount. The latter allows for time disparities of a few minutes. The timestamp should never need to be adjusted for timezones because a UNIX epoch timestamp always uses UTC/GMT.

To see an example of how to generate a hook, take a look at the lambda.py file.

Configuration

The configuration file for the server is config.py. This repo includes a template file you'll need to copy to config.py.

• SIG_HASH_ITERATIONS: Number of iterations to hash the signature.
• SIG_TIMESTAMP_EXPIRATION: Seconds after timestamp to no longer accept the timestamp as valid. (Default: 300 or 5 minutes)
• SIG_TIMESTAMP_FUTURE: Seconds before timestamp to no longer accept the timestamp as valid. (Default -90 or 3 minutes)
• TRIGGERS: a dictionary of the triggers this server accepts. Keys are the repo-branch repo key.
  • token: Randomly generated string shared between the server and the webhook generator.
  • cmd: A command to run after a signature has been validated.
  • iterations: Same as SIG_HASH_ITERATIONS. (Optional; default: SIG_HASH_ITERATIONS)