Terraform AWS CodeBuild Runner Project

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.

---

🛠️ Prerequisites

• 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.

✨ Features

• 🚀 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

---

📦 Module Usage Examples

See the examples dir for examples of usage:

1. Access level - Repo | Compute - EC2 | Mode - Container
2. Access level - Org | Compute - Lambda (4 GB) | Mode - Container
3. Repo-level access with additional webhook filter

---

🧩 Default Filter Groups

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"
  }
]

---

🔧 Input Variables

Requirements

Name	Version
terraform	>= 1.0.0
aws	>= 5.0.0

Providers

Name	Version
aws	5.95.0

Modules

No modules.

Resources

Name	Type
aws_codebuild_project.this	resource
aws_codebuild_source_credential.ssm	resource
aws_codebuild_webhook.this	resource
aws_secretsmanager_secret.this	resource
aws_secretsmanager_secret_policy.this	resource
aws_secretsmanager_secret_version.this	resource
aws_caller_identity.current	data source
aws_iam_policy_document.this	data source
aws_iam_role.role	data source
aws_ssm_parameter.github_personal_access_token	data source

Inputs

Name	Description	Type	Default	Required
additional_filter_groups	Additional filter groups to be appended to the default	list(list(object({ type = string pattern = string exclude_matched_pattern = optional(bool) })))	[]	no
build_timeout	Build timeout in minutes	number	5	no
cloudwatch_logs_group_name	Name of the CloudWatch log group	string	""	no
cloudwatch_logs_stream_name	Name of the CloudWatch log stream	string	""	no
codeconnections_arn	preauthorized ARN of the CodeConnection	string	null	no
description	Description of the CodeBuild project	string	""	no
docker_server_compute_type	Compute type for the Docker server. Default: null. Valid values: BUILD_GENERAL1_SMALL, BUILD_GENERAL1_MEDIUM, BUILD_GENERAL1_LARGE, BUILD_GENERAL1_XLARGE, and BUILD_GENERAL1_2XLARGE.	string	null	no
docker_server_security_group_ids	The list of Security Group IDs for the Docker server.	list(string)	null	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_image_pull_creds	Type of credentials AWS CodeBuild uses to pull images in your build. Valid values: CODEBUILD, SERVICE_ROLE.	string	"CODEBUILD"	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
github_personal_access_token_ssm_parameter	The GitHub personal access token to use for accessing the repository. If not specified then GitHub auth must be configured separately.	string	null	no
name	Name of the CodeBuild project	string	n/a	yes
pat_override	Is the PAT provided an override of the default account token. Default: true	bool	true	no
privileged_mode	Is privileged mode enabled for AWS CodeBuild. Required for Docker builds. Default: false	bool	false	no
service_role_name	IAM role name for CodeBuild to assume	string	n/a	yes
source_buildspec	The build spec declaration to use for this build project's related builds. Enter a path from your repository's root dir.	string	null	no
source_git_submodules_config_fetch	Whether to fetch Git submodules for the AWS CodeBuild build project.	bool	false	no
source_location	The git remote address for the repository	string	"CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION"	no
vpc_id	The VPC ID for AWS CodeBuild to launch ephemeral instances in.	string	null	no
vpc_security_group_ids	The list of Security Group IDs for AWS CodeBuild to launch ephemeral EC2 instances in.	list(string)	[]	no
vpc_subnet_ids	The list of Subnet IDs for AWS CodeBuild to launch ephemeral EC2 instances in.	list(string)	[]	no

Outputs

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 to false.
• scope_configuration is applied only when source_location is default or unset.

---

✅ Tested With

• Terraform v1.5+
• AWS Provider v5.x
• GitHub + CodeConnections integration
• Default and additional filter group handling