This Terraform module provisions an AWS CodeBuild Runner project with an attached webhook. Currently, AWS does not support creating Runner Projects via API or CLI. This module is a workaround. Terraform creates a default project and, by applying certain webhooks, it converts the project into a Runner project. This module is useful for teams that want to run GitHub Actions on AWS-managed on-demand compute.
- A GitHub App "AWS Connector for GitHub" successfully installed and configured in your AWS account. More info on that
- CodeConnection itself can be provisioned via Terraform but requires manual authorization from AWS. The module will fail if the connection is not authorized.
- 🚀 Provisions a CodeBuild Runner project using GitHub as the source (via CodeConnections)
- 📦 Adds default filter groups to capture key events (indirectly creates a runner project without official support)
- ➕ Supports additional user-supplied filter groups
- 🧠 Automatically configures
scope_configuration
when applicable (i.e., webhook access at repo level vs org level) - 🔁 Defaults to Lambda compute with 2 GB memory, Linux OS, and Node.js runtime
See the examples dir for examples of usage:
- Access level - Repo | Compute - EC2 | Mode - Container
- Access level - Org | Compute - Lambda (4 GB) | Mode - Container
- Repo-level access with additional webhook filter
This default filter group is the core logic that triggers creation of a runner project. Since AWS does not officially support provisioning CodeBuild runner projects via API, this webhook indirectly transforms a default CodeBuild project into a runner-enabled project.
[ # group 1
{
type = "EVENT"
pattern = "WORKFLOW_JOB_QUEUED"
}
]
Name | Version |
---|---|
terraform | >= 1.0.0 |
aws | >= 5.0.0 |
Name | Version |
---|---|
aws | >= 5.0.0 |
No modules.
Name | Type |
---|---|
aws_codebuild_project.this | resource |
aws_codebuild_webhook.this | resource |
Name | Description | Type | Default | Required |
---|---|---|---|---|
additional_filter_groups | Additional filter groups to be appended to the default | list(list(object({ |
[] |
no |
build_timeout | Build timeout in minutes | number |
5 |
no |
codeconnections_arn | preauthorized ARN of the CodeConnection | string |
n/a | yes |
description | Description of the CodeBuild project | string |
"" |
no |
environment_compute_type | BUILD_GENERAL1_SMALL, BUILD_GENERAL1_MEDIUM, BUILD_LAMBDA_2GB, BUILD_LAMBDA_4GB, etc | string |
"BUILD_LAMBDA_2GB" |
no |
environment_image | applicable image of ec2 or lambda | string |
"aws/codebuild/amazonlinux-x86_64-lambda-standard:nodejs20" |
no |
environment_type | LINUX_CONTAINER for EC2 and LINUX_LAMBDA_CONTAINER for Lambda | string |
"LINUX_LAMBDA_CONTAINER" |
no |
github_org_name | Name of your github org if webhook is of org level | string |
n/a | yes |
name | Name of the CodeBuild project | string |
n/a | yes |
service_role_arn | IAM role ARN for CodeBuild to assume | string |
n/a | yes |
source_location | The git remote address for the repository | string |
"CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION" |
no |
Name | Description |
---|---|
project_arn | n/a |
project_name | n/a |
ℹ️ Notes:
- A default filter group is always added to transform the project into a runner project.
additional_filter_groups
are appended after the default filter group.- Each additional group must contain a filter with
type = "EVENT"
.exclude_matched_pattern
is optional and defaults tofalse
.scope_configuration
is applied only whensource_location
is default or unset.
- Terraform v1.5+
- AWS Provider v5.x
- GitHub + CodeConnections integration
- Default and additional filter group handling