AWS GitHub Boilerplate

tl;dr

A boilerplate that contains the foundations for building an application that reacts to webhooks from a GitHub App, deployed to AWS.

Motivation

There are many different ways to deploy an application to AWS which respond to webhooks from GitHub, this repository is homing one approach that contains the following best practises:

• Using two factor authentication on the incoming webhook (IP and webhook secret validation).
• Uaing a state machine to coordinate the logic of the application.
• Leverages GitHub Apps as the proxy which fires the webhook from GitHub.

Introduction

Do you want to deploy an application to AWS that responds to a GitHub Webhook? This boilerplate may be useful to you.

Pre-requisite

This repository does require some knowledge of:

• GitHub Apps
• AWS

You do not need to be an expert, but it helps having some foundational knowledge.

The documentation in this repository also assums a techincal audience.

Getting Started

Stage One: Use template.

1. Generate a new repository off this template by clicking the Use Template option.

Stage Two: AWS Role, Enviroment and Secrets Setup

This repository makes use of the in-built OIDC feature within GitHub workflows. Please read the following article on how to get setup. Create a role within AWS IAM and configure the role to use OpenID Connect. More instructions can be found here: Configuring OpenID Connect in Amazon Web Services.

When you create the role, attach the following policies:

Once you have created your role, and set up the identity, please:

1. Create a new GitHub Enviroment called main.
2. In the main enviroment, create a GitHub secret called AWS_ACCOUNT_ID. Put the AWS Account ID here where the role is created.
3. In the main enviroment, create a GitHub secret calledAWS_ROLE_NAME: Put the AWS IAM role name here.

Warning: We recommend you update your AWS IAM Role to filter the subject claim from the main environment. See instructions on how to do that here. This adds another layer of protection.

Stage Three: Create a GitHub App

Create a GitHub App, using these instructions.

Warning: You are welcome to put dummy values in the input fields for the new app, as we don't know the right values yet. The only value you need to put a valud value in is: Webhook Secret, please put the a seret in here, that you will

Stage Four: Update AWS Systems Manager (Parameter Store)

Create the following parameters in AWS Systems Manager.

1. /github-boilerplate/APP_CLIENT_ID: The GitHub App Client ID.
2. /github-boilerplate/APP_CLIENT_SECRET: The GitHub App Client Secret.
3. /github-boilerplate/APP_ID: The GitHub App ID.
4. /github-boilerplate/APP_INSTALLATION_ID: The GitHub App Installation ID.
5. /github-boilerplate/APP_PRIVATE_KEY: The GitHub App Private Key.
6. /github-boilerplate/GITHUB_WEBHOOKS_SECRET: The secret you assigned to the webhook.

Stage Five: Run the Deploy

You can run the workflow manually using the workflow_dispatch event.

Stage Six: Test the Deploy

Once the deploy has been kicked off, it's worth checking the github workflow output and also the cloud formation output. Check logs for any errors and correct as needed.

Warning There are likely edge cases that have not been taken into consideration. As you find errors, please open issues on this repository and we will update the README.