{"_id":"@mapbox/aws-github-webhook","_rev":"263-58012239a2f2fd1a53a42afc18efff85","name":"@mapbox/aws-github-webhook","description":"Create an API Gateway endpoint to receive Github webhooks","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@mapbox/aws-github-webhook","version":"1.0.0","description":"Create an API Gateway endpoint to receive Github webhooks","main":"index.js","repository":{"type":"git","url":"git+ssh://git@github.com/mapbox/aws-github-webhook.git"},"author":{"name":"Mapbox"},"license":"MIT","scripts":{"test":"validate-template test/index.test.js","example":"build-template test/index.test.js"},"devDependencies":{"eslint":"^3.19.0","eslint-plugin-node":"^4.2.2"},"dependencies":{"@mapbox/cloudfriend":"^1.8.1"},"gitHead":"9370cb9b55ee0b0d100f4fe1935ea21fb27b113a","bugs":{"url":"https://github.com/mapbox/aws-github-webhook/issues"},"homepage":"https://github.com/mapbox/aws-github-webhook#readme","_id":"@mapbox/aws-github-webhook@1.0.0","_shasum":"eedc577403e91f9bbe707a4a5a63ada30b070574","_from":".","_npmVersion":"3.10.10","_nodeVersion":"6.10.0","_npmUser":{"name":"rclark","email":"ryan.clark.j@gmail.com"},"dist":{"shasum":"eedc577403e91f9bbe707a4a5a63ada30b070574","tarball":"https://registry.npmjs.org/@mapbox/aws-github-webhook/-/aws-github-webhook-1.0.0.tgz","integrity":"sha512-X6UYDggtEhpCDWQvHCZnhu6J2gFwiXk0VMc6VdJ2rhHDKn4iBhpZFxLgDdzbHnCxTZH0PJeF2JmPjwkQ4PXvQA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIF+Q9ZA+fM+rte2ulxctGLC9fJcOGWcC7ujD+X4AhmSmAiBmWpPww/rdSK+sCzoy8903SShneKU2Slvlh+ZdidyM3w=="}]},"maintainers":[{"name":"rclark","email":"ryan.clark.j@gmail.com"}],"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/aws-github-webhook-1.0.0.tgz_1494112258267_0.2330754091963172"},"directories":{}}},"readme":"# aws-github-webhook\n\nA simple helper to build a connection between Github webhooks and your AWS Lambda functions.\n\n## When to use it\n\nUse 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.\n\n## What it does\n\nThis 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.\n\nYou provide a Lambda function that reacts to push events, and we provide the rest.\n\n## The data your Lambda function receives\n\nIt will be a shortened version of a [Github push event](https://developer.github.com/v3/activity/events/types/#pushevent). Here's an example:\n\n```json\n{\n  \"ref\": \"refs/head/changes\",\n  \"after\": \"0d1a26e67d8f5eaf1f6ba5c57fc3c7d91ac0fd1c\",\n  \"before\": \"9049f1265b7d61be4a8904a9a27120d2064dab3b\",\n  \"deleted\": false,\n  \"repository\": {\n    \"name\": \"public-repo\",\n    \"owner\": {\n      \"name\": \"baxterthehacker\"\n    }\n  },\n  \"pusher\": {\n    \"name\": \"baxterthehacker\"\n  }\n}\n```\n\nHowever 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:\n\n```js\nmodule.exports.handler = (event, context, callback) => {\n  const message = JSON.parse(event.Records[0].Sns.Message);\n}\n```\n\n## How to use this module\n\n1. Create a CloudFormation template (in JavaScript) that defines\n  - a Lambda function that will react to Github webhook payloads, and perform whatever actions you wish to tak on each push, and\n  - the IAM role that your Lambda function will need in order to accomplish its task.\n2. Use the JavaScript function exported by this module to create the rest of the resources required. Merge those resources with your own using [cloudfriend](https://github.com/mapbox/cloudfriend).\n3. Create the CloudFormation stack by deploying your template using [cfn-config](https://github.com/mapbox/cfn-config).\n4. 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`.\n\n## Example CloudFormation template\n\nYou should make a CloudFormation template file that looks similar to this:\n\n```js\nconst cf = require('@mapbox/cloudfriend');\nconst buildWebhook = require('@mapbox/aws-github-webhook');\n\nconst myTemplate = {\n  Resources: {\n    MyLambda: {\n      Type: 'AWS::Lambda::Function',\n      Properties: {\n        Code: {\n          S3Bucket: 'my-bucket',\n          S3Key: 'my-code.zip'\n        },\n        FunctionName: 'MyGithubWebhook',\n        Handler: 'index.handler',\n        MemorySize: 256,\n        Runtime: 'nodejs6.10',\n        Timeout: 300,\n        Role: cf.getAtt('LambdaRole', 'Arn')\n      }\n    },\n    LambdaRole: {\n      Type: 'AWS::IAM::Role',\n      Properties: {\n        AssumeRolePolicyDocument: {\n          Statement: [\n            {\n              Effect: 'Allow',\n              Principal: { Service: 'lambda.amazonaws.com' },\n              Action: 'sts:AssumeRole'\n            }\n          ]\n        },\n        Policies: [\n          {\n            PolicyName: 'write-logs',\n            PolicyDocument: {\n              Statement: [\n                {\n                  Effect: 'Allow',\n                  Action: 'logs:*',\n                  Resource: 'arn:aws:logs:*'\n                }\n              ]\n            }\n          }\n        ]\n      }\n    }\n  }\n};\n\nconst webhook = buildWebhook('MyLambda');\n\nmodule.exports = cf.merge(myTemplate, webhook);\n```\n\n## Using the Serverless Application Model\n\nThis 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:\n\n```js\nconst cf = require('@mapbox/cloudfriend');\nconst buildWebhook = require('@mapbox/aws-github-webhook');\n\nconst myTemplate = {\n  Resources: {\n    MyLambda: {\n      Type: 'AWS::Serverless::Function',\n      Properties: {\n        Handler: 'index.handler',\n        Runtime: 'nodejs6.10',\n        CodeUri: 's3://my-bucket/my-code.zip'\n      }\n    }\n  }\n};\n\nconst webhook = buildWebhook('MyLambda');\n\nmodule.exports = cf.merge(myTemplate, webhook);\n```\n\n## View a complete example template as JSON\n\nIf 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.\n\n```\n$ cd ~/aws-github-webhook\n$ npm run example\n```\n","maintainers":[{"email":"yannick.meeus+npm+production+ci@mapbox.com","name":"mbx-npm-ci-production"},{"email":"yannick.meeus+npm+staging+ci@mapbox.com","name":"mbx-npm-ci-staging"},{"email":"yannick.meeus+npm+prod+advanced+actions@mapbox.com","name":"mbx-npm-advanced-actions-production"},{"email":"yannick.meeus+npm+staging+advanced+actions@mapbox.com","name":"mbx-npm-advanced-actions-staging"},{"email":"yannick.meeus+npm+prod+09@mapbox.com","name":"mbx-npm-09-production"},{"email":"yannick.meeus+npm+prod+08@mapbox.com","name":"mbx-npm-08-production"},{"email":"yannick.meeus+npm+prod+07@mapbox.com","name":"mbx-npm-07-production"},{"email":"yannick.meeus+npm+prod+06@mapbox.com","name":"mbx-npm-06-production"},{"email":"yannick.meeus+npm+prod+05@mapbox.com","name":"mbx-npm-05-production"},{"email":"yannick.meeus+npm+prod+04@mapbox.com","name":"mbx-npm-04-production"},{"email":"yannick.meeus+npm+prod+03@mapbox.com","name":"mbx-npm-03-production"},{"email":"yannick.meeus+npm+prod+02@mapbox.com","name":"mbx-npm-02-production"},{"email":"yannick.meeus+npm+prod+01@mapbox.com","name":"mbx-npm-01-production"},{"email":"yannick.meeus@mapbox.com","name":"mbx-npm-02-staging"},{"email":"accounts+npmjs-01@mapbox.com","name":"mapbox-npm-01"},{"email":"accounts+npmjs-02@mapbox.com","name":"mapbox-npm-02"},{"email":"accounts+npmjs-07@mapbox.com","name":"mapbox-npm-07"},{"email":"accounts+npmjs-03@mapbox.com","name":"mapbox-npm-03"},{"email":"accounts+npmjs-04@mapbox.com","name":"mapbox-npm-04"},{"email":"accounts+npmjs-09@mapbox.com","name":"mapbox-npm-09"},{"email":"accounts+npmjs-05@mapbox.com","name":"mapbox-npm-05"},{"email":"accounts+npmjs-06@mapbox.com","name":"mapbox-npm-06"},{"email":"accounts+npmjs-08@mapbox.com","name":"mapbox-npm-08"},{"email":"accounts+npmjs-advanced-actions@mapbox.com","name":"mapbox-npm-advanced-actions"},{"email":"accounts+npmjs-npm-ci@mapbox.com","name":"mapbox-npm-ci"},{"email":"accounts+npmjs@mapbox.com","name":"mapbox-npm"},{"email":"accounts@mapbox.com","name":"mapbox-admin"},{"email":"accounts+npm-mapbox-machine-user@mapbox.com","name":"mapbox-machine-user"}],"time":{"modified":"2023-01-12T12:41:02.253Z","created":"2017-05-06T23:10:58.528Z","1.0.0":"2017-05-06T23:10:58.528Z"},"homepage":"https://github.com/mapbox/aws-github-webhook#readme","repository":{"type":"git","url":"git+ssh://git@github.com/mapbox/aws-github-webhook.git"},"author":{"name":"Mapbox"},"bugs":{"url":"https://github.com/mapbox/aws-github-webhook/issues"},"license":"MIT","readmeFilename":"readme.md"}