{"id":19652721,"url":"https://github.com/advanced-security/aws-github-boilerplate","last_synced_at":"2025-04-30T19:43:21.303Z","repository":{"id":78544366,"uuid":"570297806","full_name":"advanced-security/aws-github-boilerplate","owner":"advanced-security","description":"A boilerplate for an application reacting to webhooks from GitHub, deployed to AWS. ","archived":false,"fork":false,"pushed_at":"2023-07-20T03:43:29.000Z","size":496,"stargazers_count":3,"open_issues_count":7,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T19:22:26.663Z","etag":null,"topics":["aws","boilerplate-template","github-apps","webhooks"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/advanced-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-24T20:36:25.000Z","updated_at":"2024-10-02T15:42:00.000Z","dependencies_parsed_at":"2023-10-10T14:01:57.761Z","dependency_job_id":null,"html_url":"https://github.com/advanced-security/aws-github-boilerplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Faws-github-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Faws-github-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Faws-github-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/advanced-security%2Faws-github-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/advanced-security","download_url":"https://codeload.github.com/advanced-security/aws-github-boilerplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251772214,"owners_count":21641400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","boilerplate-template","github-apps","webhooks"],"created_at":"2024-11-11T15:11:52.824Z","updated_at":"2025-04-30T19:43:21.259Z","avatar_url":"https://github.com/advanced-security.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS GitHub Boilerplate\n\n## tl;dr\n\nA boilerplate that contains the foundations for building an application that reacts to webhooks from a [GitHub App](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps), deployed to [AWS](https://aws.amazon.com/?nc2=h_lg).\n\n## Motivation\n\nThere 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:\n\n- Using two factor authentication on the incoming webhook (IP and webhook secret validation).\n- Uaing a state machine to coordinate the logic of the application.\n- Leverages GitHub Apps as the proxy which fires the webhook from GitHub.\n\n## Introduction\n\nDo you want to deploy an application to AWS that responds to a GitHub Webhook? This boilerplate may be useful to you.\n\n## Pre-requisite\n\nThis repository does require some knowledge of:\n\n- [GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps)\n- [AWS](https://aws.amazon.com/?nc2=h_lg)\n\nYou do not need to be an expert, but it helps having some foundational knowledge.\n\nThe documentation in this repository also assums a techincal audience.\n\n## Getting Started\n\n#### Stage One: Use template.\n\n1. Generate a new repository off this template by clicking the [Use Template](https://github.com/advanced-security/aws-github-boilerplate/generate) option.\n\n#### Stage Two: AWS Role, Enviroment and Secrets Setup\n\nThis 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](https://docs.github.com/en/enterprise-cloud@latest/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services).\n\nWhen you create the role, attach the following policies:\n\n\u003cimg width=\"1342\" alt=\"AWS IAM Role\" src=\"https://user-images.githubusercontent.com/6696451/209571182-8af0a3f5-bf0f-478f-b187-a2dfff0447f8.png\"\u003e\n\nOnce you have created your role, and set up the identity, please:\n\n1. Create a new [GitHub Enviroment](https://docs.github.com/en/enterprise-cloud@latest/actions/deployment/targeting-different-environments/using-environments-for-deployment) called `main`.\n1. In the `main` enviroment, create a GitHub secret called `AWS_ACCOUNT_ID`. Put the AWS Account ID here where the role is created.\n1. In the `main` enviroment, create a GitHub secret called`AWS_ROLE_NAME`: Put the AWS IAM role name here.\n\n\u003e **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](https://docs.github.com/en/enterprise-cloud@latest/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#filtering-for-a-specific-environment). This adds another layer of protection.\n\n#### Stage Three: Create a GitHub App\n\nCreate a GitHub App, [using these instructions](https://docs.github.com/en/enterprise-cloud@latest/developers/apps/building-github-apps/creating-a-github-app).\n\n\u003e **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\n\n#### Stage Four: Update AWS Systems Manager (Parameter Store)\n\nCreate the following parameters in AWS Systems Manager.\n\n1. `/github-boilerplate/APP_CLIENT_ID`: The GitHub App Client ID.\n2. `/github-boilerplate/APP_CLIENT_SECRET`: The GitHub App Client Secret.\n3. `/github-boilerplate/APP_ID`: The GitHub App ID.\n4. `/github-boilerplate/APP_INSTALLATION_ID`: The GitHub App Installation ID.\n5. `/github-boilerplate/APP_PRIVATE_KEY`: The GitHub App Private Key.\n6. `/github-boilerplate/GITHUB_WEBHOOKS_SECRET`: The secret you assigned to the webhook.\n\n#### Stage Five: Run the Deploy\n\nYou can run the workflow manually using the [workflow_dispatch](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) event.\n\n#### Stage Six: Test the Deploy\n\nOnce 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.\n\n\u003e **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`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadvanced-security%2Faws-github-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadvanced-security%2Faws-github-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadvanced-security%2Faws-github-boilerplate/lists"}