{"id":18525790,"url":"https://github.com/toricls/github-codebuild-integration","last_synced_at":"2025-04-09T12:31:32.383Z","repository":{"id":40210343,"uuid":"101245283","full_name":"toricls/github-codebuild-integration","owner":"toricls","description":"Run and Integrate AWS CodeBuild with GitHub Push/Pull-Request webhook events.","archived":false,"fork":false,"pushed_at":"2023-07-18T23:57:59.000Z","size":169,"stargazers_count":103,"open_issues_count":11,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T05:35:14.916Z","etag":null,"topics":["aws-codebuild","ci","github-integration","serverless","webhook"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toricls.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-08-24T02:28:43.000Z","updated_at":"2024-08-13T20:27:15.000Z","dependencies_parsed_at":"2024-11-06T17:50:38.532Z","dependency_job_id":"a3df99a8-edf8-425c-88fb-0154387e0e17","html_url":"https://github.com/toricls/github-codebuild-integration","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Fgithub-codebuild-integration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Fgithub-codebuild-integration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Fgithub-codebuild-integration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toricls%2Fgithub-codebuild-integration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toricls","download_url":"https://codeload.github.com/toricls/github-codebuild-integration/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248040325,"owners_count":21037848,"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-codebuild","ci","github-integration","serverless","webhook"],"created_at":"2024-11-06T17:47:02.829Z","updated_at":"2025-04-09T12:31:27.370Z","avatar_url":"https://github.com/toricls.png","language":"JavaScript","readme":"# github-codebuild-integration (gci)\n\n[![GitHub release](https://img.shields.io/github/release/toricls/github-codebuild-integration.svg?style=flat-square)][release]\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)][license]\n\n[release]: https://github.com/toricls/github-codebuild-integration/releases\n[license]: https://github.com/toricls/github-codebuild-integration/blob/master/LICENSE\n\n`gci` is a CI dispatching/status handling tool to integrate AWS CodeBuild with GitHub Push/Pull-Request webhook events, created with love of Serverless Architecture.\n\n## Overview\n\nYay, Serverless!\n\n[![Overview](https://github.com/toricls/github-codebuild-integration/wiki/res/overview-800x463.png)](https://github.com/toricls/github-codebuild-integration/wiki/res/overview.png)\n\n**Commits:**\n\n[![Commits](https://github.com/toricls/github-codebuild-integration/wiki/res/commits-300x234.png)](https://github.com/toricls/github-codebuild-integration/wiki/res/commits.png)\n\n**Pull Request:**\n\n[![Pull Request](https://github.com/toricls/github-codebuild-integration/wiki/res/pr-600x394.png)](https://github.com/toricls/github-codebuild-integration/wiki/res/pr.png)\n\n## Features\n\n- Invoking a pre-configured AWS CodeBuild project by hooking Push or Pull Reqeust webhook events.\n- Setting GitHub's CI status based on status/result of builds on AWS CodeBuild.\n\n### AWS account / gci / GitHub repository\n\ngci allows you to provision multiple installations in one AWS account as follows:\n\nResources | Relation\n---------- | ----------\nAWS account : gci installations | 1 : n\ngci installation : GitHub repository | 1 : 1\nGitHub repository : AWS CodeBuild project | 1 : 1 (will be extended to 1 : n in the future)\n\nAs mentioned above, gci can be installed as many as you want to integrate with your GitHub repositories. If you want to build 3 repositories, you may provision 3 of gci installation for instance.\n\n## Background\n\nGitHub has a feature to show each commit's status like 'success', 'failure', 'pending' on their Commit/PR pages, and based on that status, we can protect any branches from CI failed branch to be merged.\n\nGitHub accepts status creation via their APIs and many third-party CI services implement functionalities to integrate with that APIs to show their job status on GitHub.\n\n~~On the other hand, AWS CodeBuild doesn't have such a feature to save its build project status to GitHub for now. gci is a missing piece of AWS CodeBuild to make things better.~~ I heard that AWS CodeBuild now supports for building by GitHub push/PR and for updating GitHub status natively. We'll find another motivation to keep developing gci :stuck_out_tongue:\n\n## Requirements\n\n### Prerequisites\n\ngci requires the following to be installed on your AWS account.\n\n### Required Tools\n\nWe use a Makefile to manage gci's lifecycle.\n\n- GNU Make (if you are using macOS, `brew install make` is handy)\n\nThe Makefile depends on the following tools:\n\n- Node.js v14.1.0 or later\n- Yarn 1.22.0 or later\n- AWS-CLI 1.11.132 or later\n- curl\n\n### Required Accounts \u0026 Resources\n\n- AWS Account\n- `AdministratorAccess` to your AWS Account (to use AWS CloudFormation in the installation command)\n- GitHub Account\n\nAnd the listed resources below are created in the process of installation, which means they are required as available AWS services in a region where you want to run gci.\n\n- Amazon S3\n- Amazon SNS\n- Amazon CloudWatch Events\n- AWS Lambda\n- AWS CodeBuild\n- AWS IAMv\n- AWS CloudFormation\n\n## Installation\n\n_**NOTE: Make sure you already have:**_  \n_**- [AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) for AWS CLI access.**_  \n_**- at least one AWS CodeBuild project created.**_\n\n### AWS Account-wide Resource\n\nCreate an S3 Bucket to store gci's artifacts to proceed.\n\n```\n$ aws s3api create-bucket \\\n    --bucket {YOUR_S3_BUCKET_NAME} \\\n    --create-bucket-configuration LocationConstraint=$AWS_DEFAULT_REGION\n```\n\n_**NOTE: Create an S3 bucket for each AWS region if you use gci in multiple AWS regions.**_\n\n### Per-Project Resources\n\n#### Clone this repository\n\n```\n$ git clone https://github.com/toricls/github-codebuild-integration.git\n$ cd $(pwd)/github-codebuild-integration\n```\n\n#### Create GitHub Personal Access Token\n\nOpen [New personal access token](https://github.com/settings/tokens/new) page and create one for a gci's installation.\n\nInput token description like `codebuild-YOUR_REPO_NAME` and enable `admin:repo_hook` and `repo:status` as scopes, then click the `Generate token` button.\n\nCopy the personal access token value and proceed to the next section, \"Configure parameters\".\n\n#### Configure parameters\n\nCopy example configuration file and edit it to configure paramters for your GitHub repository.\n\n```\n$ export YOUR_PROJECT_NAME=xxxxxxxxxxxxxxxxx\n$ cp env/example.env env/$YOUR_PROJECT_NAME.env\n$ editor env/$YOUR_PROJECT_NAME.env\n```\n\nNext table describes about all available parameters of gci.\n\nRequired | Parameter Name | What is this | Example\n------------ | ------------ | ------------- | ------------- \nyes | S3_SAM_ARTIFACTS_BUCKET_NAME | An S3 bucket to store AWS SAM's artifacts. Set the name of the S3 bucket you created on previous step. | your.sam.artifacts.bucket\nyes | GITHUB_REPOSITORY_URL | A repository URL you wanted build. Use https style path and make sure trailing '.git' is removed. | https://github.com/your-org/your-repo\nyes | GITHUB_PERSONAL_ACCESS_TOKEN | Used for updating GitHub PR's status and Webhook configuration. Minimum scope are `admin:repo_hook` and `repo:status`. You can create and obtain a new token via [settings page](https://github.com/settings/tokens/new). | your-github-personal-access-token\nyes | GITHUB_TARGET_RESOURCE | Choose one event to decide when your CodeBuild project runs. Available value is `pr` or `push`. | push\noptional | GITHUB_IGNORE_BRANCH_REGEX | Regex string to specify branch name to ignore commit events. This parameter will be enabled only the `GITHUB_TARGET_RESOURCE` value is `push`. | wip.*\nyes | AWS_DEFAULT_REGION | The region where you want to provision this tool via CloudFormation. | us-east-1\nyes | CODEBUILD_PROJECT_NAME | The AWS CodeBuild project name you've already configured for your GitHub repository. | your-codebuild-project-name\nyes | CODEBUILD_PROJECT_REGION | The region where you've created a CodeBuild project. You can specify a different region from the region of CloudFormation. | us-east-1\noptional | BUILD_SKIPPED_BY | Build invocation will be skipped if the head commit message includes the value of this parameter. This parameter will be used only the GITHUB_TARGET_RESOURCE value is `push`. | \"skip ci\"\n\n#### Deploy\n\nPackage all artifacts and deploy to your AWS account. You can use this command to update your existing gci installation.\n\n```\n$ make deploy ENV_FILE_PATH=env/$YOUR_PROJECT_NAME.env\n```\n\n## Uninstall\n\nYou can delete most of generated resources by executing:\n\n```\n$ make destroy ENV_FILE_PATH=env/YOUR-PROJECT-NAME.env\n```\n\n_**NOTE: CloudFormation doesn't delete CloudWatch's Log Groups. You may want to remove it manually on the AWS Management Console or via the AWS CLI. Also you may want to remove the S3 Bucket(s) you created.**_\n\n## FAQ\n\n### Installation \u0026 Uninstallation\n\nQ. My IAM role is too weak to install your tool, I guess.\n\nA. Ask your administrator and show him/her the following:\n- [Required Accounts \u0026 Resources][required-accounts--resources] section\n- This tool uses CloudFormation with `--capabilities \"CAPABILITY_IAM\"` option\n\n[required-accounts--resources]: https://github.com/toricls/github-codebuild-integration/blob/master/README.md#required-accounts--resources\n\nQ: I want to remove all resources of gci from my AWS account.\n\nA: Read the [Uninstall][uninstall] section above :X\n\n[uninstall]: https://github.com/toricls/github-codebuild-integration/blob/master/README.md#uninstall\n\n### Changing Configurations\n\nQ: I changed my repository name after gci install.\n\nA: Change the value of `GITHUB_REPOSITORY_URL` in your env file, then deploy again.\n\nQ: I want to stop CI invoking for a bit.\n\nA: Open `GitHubWebhookHandler` function (the function name on the Lambda Management Console may something like `YOUR-PROJECT-NAME-GitHubWebhookHandler-XXXXXXXXXXX`), then set `true` to the environment variable `DO_NOT_RUN`.  \nDon't forget to back that value to `false` after your quick work.\n\n### Feature Request\n\nQ: I need more than one AWS CodeBuild project for my GitHub repository.\n\nA: I totally agree with you! It will be supported in the future. I think the feature will be implemented with a mapping configuration for 'branch name reg-expressions' and 'AWS CodeBuild projects'. But PRs are always welcome :smiley:\n\nQ. Can you change the icon which shown at PR page's CI status?\n\nA. GitHub shows the avatar of the user who owns the personal access token you provided. You can change the icon by using something like [Machine users](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) to create a personal access token for gci.\n\n## Contribution\n\n1. Fork ([https://github.com/toricls/github-codebuild-integration/fork](https://github.com/toricls/github-codebuild-integration/fork))\n1. Create a feature branch\n1. Commit your changes\n1. Rebase your local changes against the master branch\n1. Create a new Pull Request\n\n## Licence\n\n[MIT](LICENCE)\n\n## Author\n\n[toricls](https://github.com/toricls)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoricls%2Fgithub-codebuild-integration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoricls%2Fgithub-codebuild-integration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoricls%2Fgithub-codebuild-integration/lists"}