aws-github-webhook

A simple helper to build a connection between Github webhooks and your AWS Lambda functions.

When to use it

Use this module when you wish to invoke a Lambda function in reaction to webhooks delivered by Github in response to push actions only. Over time, this library may grow to support other event types.

What it does

This library provides you with a set of CloudFormation resources to include in a CloudFormation template alongside the Lambda function you wish to have invoked. The provided resources define an API Gateway endpoint and functionality to authenticate webhook payloads coming from Github.

You provide a Lambda function that reacts to push events, and we provide the rest.

The data your Lambda function receives

It will be a shortened version of a Github push event. Here's an example:

{
  "ref": "refs/head/changes",
  "after": "0d1a26e67d8f5eaf1f6ba5c57fc3c7d91ac0fd1c",
  "before": "9049f1265b7d61be4a8904a9a27120d2064dab3b",
  "deleted": false,
  "repository": {
    "name": "public-repo",
    "owner": {
      "name": "baxterthehacker"
    }
  },
  "pusher": {
    "name": "baxterthehacker"
  }
}

However that data will be "wrapped" a few levels deep. To access the data as a JavaScript object, you will want your Lambda function's code to parse the incoming event as follows:

module.exports.handler = (event, context, callback) => {
  const message = JSON.parse(event.Records[0].Sns.Message);
}

How to use this module

1. Create a CloudFormation template (in JavaScript) that defines

• a Lambda function that will react to Github webhook payloads, and perform whatever actions you wish to tak on each push, and
• the IAM role that your Lambda function will need in order to accomplish its task.

2. Use the JavaScript function exported by this module to create the rest of the resources required. Merge those resources with your own using cloudfriend.
3. Create the CloudFormation stack by deploying your template using cfn-config.
4. Your stack will output the URL for your webhook's endpoint, and a secret token. Provide these values to Github as a new webhook (see settings/hooks/new for your repository). Make sure to specify the Content type as application/json.

Example CloudFormation template

You should make a CloudFormation template file that looks similar to this:

const cf = require('@mapbox/cloudfriend');
const buildWebhook = require('@mapbox/aws-github-webhook');

const myTemplate = {
  Resources: {
    MyLambda: {
      Type: 'AWS::Lambda::Function',
      Properties: {
        Code: {
          S3Bucket: 'my-bucket',
          S3Key: 'my-code.zip'
        },
        FunctionName: 'MyGithubWebhook',
        Handler: 'index.handler',
        MemorySize: 256,
        Runtime: 'nodejs6.10',
        Timeout: 300,
        Role: cf.getAtt('LambdaRole', 'Arn')
      }
    },
    LambdaRole: {
      Type: 'AWS::IAM::Role',
      Properties: {
        AssumeRolePolicyDocument: {
          Statement: [
            {
              Effect: 'Allow',
              Principal: { Service: 'lambda.amazonaws.com' },
              Action: 'sts:AssumeRole'
            }
          ]
        },
        Policies: [
          {
            PolicyName: 'write-logs',
            PolicyDocument: {
              Statement: [
                {
                  Effect: 'Allow',
                  Action: 'logs:*',
                  Resource: 'arn:aws:logs:*'
                }
              ]
            }
          }
        ]
      }
    }
  }
};

const webhook = buildWebhook('MyLambda');

module.exports = cf.merge(myTemplate, webhook);

Using the Serverless Application Model

This can be especially useful if you have a simple lambda function that doesn't require a lot of additional AWS permissions in order to complete its work. Here's an example:

const cf = require('@mapbox/cloudfriend');
const buildWebhook = require('@mapbox/aws-github-webhook');

const myTemplate = {
  Resources: {
    MyLambda: {
      Type: 'AWS::Serverless::Function',
      Properties: {
        Handler: 'index.handler',
        Runtime: 'nodejs6.10',
        CodeUri: 's3://my-bucket/my-code.zip'
      }
    }
  }
};

const webhook = buildWebhook('MyLambda');

module.exports = cf.merge(myTemplate, webhook);

View a complete example template as JSON

If you're interested in getting a better understanding of the CloudFormation resources that are built in order to support this workflow, try taking a closer look at the full JSON behind an example template.

$ cd ~/aws-github-webhook
$ npm run example