GitHub Webhooks with Google Cloud Functions

A Google Cloud Function that handles GitHub Webhook events.

Implemented for the Node 10 runtime with no additional runtime dependencies.

GitHub to Jenkins

Modifications for Jenkins were written by Stanko Arbutina, Alen Bašić and Josip Gracin.

There are two environment variables that need to be set:

JENKINS_HOST, and
JENKINS_PORT.

Jenkins should perform authentication of webhooks using shared secret configured in GitHub plugin.

GitHub to Trello

The default handler, githubToTrello, posts comments and attachments to Trello when there is a GitHub push or pull request.

For example, Alice's team uses a Trello board, where a card is created per feature. When Alice starts working on a card, she follows a naming convention where she appends the card's shortLink (here, nqPiDKmw) to her git branch name:

https://trello.com/c/nqPiDKmw/9-grand-canyon-national-park

becomes a new branch with:

$ git checkout -b my-branch-name#nqPiDKmw

Now whenever Alice pushes to GitHub, a webhook fires to our Cloud Function, which parses the branch name for the card id (here, nqPiDKmw), and automatically adds a comment to the card that links back to the head commit of the push.

Similarly, when Alice is ready to open a pull request, the webhook fires an event, and our Cloud Function adds a link to the PR as an attachment to the card and updates a Custom Field with the PR status (the last requires the Custom Fields Power-Up to be enabled for the board).

GitHub to ???

Not a Trello user? Just add a different handler under src/handler/ and point to it from src/index.js.

Make a pull request!

Deploy

Trello

Get your Developer API Key & generate a Token: https://trello.com/app-key
Set environment variables for the API key and token:

$ export TRELLO_API_KEY=<your key here>
$ export TRELLO_TOKEN=<your token here>

Google Cloud Functions

If you've never used gcloud or deployed a Cloud Function before, run through the Quickstart to make sure you have a GCP project with the Cloud Functions API enabled before proceeding.
Generate a secret token to validate GitHub requests, e.g.:

export GITHUB_SECRET=$(node -p "require('crypto').randomBytes(20).toString('hex');")

Fork/clone this repo
Within the repo, deploy this cloud function with:

$ gcloud functions deploy githubWebhookHandler \
--trigger-http --runtime nodejs10 --memory 128MB \
--set-env-vars GITHUB_SECRET=$GITHUB_SECRET,TRELLO_API_KEY=$TRELLO_API_KEY,TRELLO_TOKEN=$TRELLO_TOKEN \
--project $(gcloud config list --format 'value(core.project)')

Note the URL of your Cloud Function (also obtainable with: gcloud functions describe githubToTrello --format 'value(httpsTrigger.url)')

GitHub

Add webhook (e.g. https://github.com/<user-or-org/<repo>/settings/hooks/new)
- Payload URL: the URL of your Cloud Function, e.g. https://<GCP_REGION>-<PROJECT_ID>.cloudfunctions.net/githubToTrello
- Content type: application/json
- Secret: the token ($GITHUB_SECRET) you generated in step 2
- Let me select individual events: Pushes, Pull requests, and Pull request reviews

Testing

Prerequisites

Node 10
npm 5.6.0 or later (yarn should be fine as well)

Unit tests

$ npm install
$ npm test

Ad-hoc tests

Spin up the local development server:

$ npm start

Craft a webhook payload (ensuring the ref points to a Trello board you have write permissions to):

$ payload='{"action":"opened","pull_request":{"html_url":"https://github.com/github/linguist/pull/11","head":{"ref":"9-grand-canyon-national-park#nqPiDKmw"}}}'
$ signature=$(node -p "github = require('./src/util/github');github.sign('${payload}')")

Issue requests against the local endpoint, e.g.:

$ curl -H "X-Hub-Signature: ${signature}" \
-H "X-GitHub-Event: pull_request" -H "X-GitHub-Delivery: 123" \
-H "Content-Type: application/json" -d ${payload} \
http://localhost:8080

For local testing of actual GitHub events:

npx smee -p 8080
Enter the url returned from the above command, e.g. "https://smee.io/abc123" as your GitHub repo's "Webhook URL"

jgracin/github-webhook-cloud-function