Skip to content

flexion/aws-codebuild-runner-project-tf-module

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

29 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

Modules

No modules.

Resources

Name Type
aws_codebuild_project.this resource
aws_codebuild_webhook.this resource

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

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

About

A Terraform module to build a codebuild hosted runner project

Resources

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages