CI Runnerscirunners.org
Runner profile · Open-source project

terraform-aws-github-runner

Answer in brief

Terraform module that runs GitHub Actions runners on EC2 spot or on-demand instances, scaled by Lambda functions. A community-maintained Terraform module for webhook-driven GitHub Actions runners on EC2; it suits AWS teams that are comfortable operating Lambda, SQS and Terraform themselves.

By the CI Runners editors · Updated

Overview

terraform-aws-github-runner is a Terraform module that creates the AWS infrastructure for self-hosted, autoscaling GitHub Actions runners on EC2. An API Gateway endpoint receives workflow_job webhook events, a queue buffers them, and Lambda functions launch instances through the EC2 CreateFleet API and remove them when they are idle. Runners scale down to zero when no workflows are active. Spot instances are the documented default lifecycle, with on-demand as an option.

Runners are reused until idle by default; the docs recommend the optional ephemeral mode, in which an instance takes a single job using a just-in-time configuration. The module covers Linux on x64 and arm64, Windows, and experimental macOS on EC2 Mac dedicated hosts, at organization or repository level. It works with github.com, GitHub Enterprise Cloud with data residency and GitHub Enterprise Server. The project was founded at Philips Labs and now lives in the github-aws-runners organisation.

Notable

  • Version 8.0.0 (21 October 2026) introduced an experimental multi-runner v2 architecture and experimental scale-set orchestration that runs a controller on ECS Fargate
  • Version 8.1.1 was released on 12 November 2026
  • The README states the repository was originally founded and maintained by Philips Labs; the github-aws-runners organisation describes itself as formerly hosted via philips-labs

terraform-aws-github-runner specifications

AttributeDetails
CI systemsGitHub Actions
Operating systemsLinux, Windows, macOS
Architecturesx64, arm64
DeploymentOpen-source project
Where it can runAWS
IsolationEach runner is an EC2 instance in your AWS account; by default runners are reused until they are idle, and in ephemeral mode each instance takes one job with a just-in-time configuration and is then terminated
Fresh environment per jobNot documented
HardwareEC2 instance types that you list, spot or on-demand, launched through the EC2 CreateFleet API; Graviton types for arm64 and EC2 Mac dedicated hosts for the experimental macOS support
Performance (vendor claim)Not documented
Runner sizesNot documented
CachingNot documented
Docker layer cachingNot documented
GPUWith dynamic labels enabled, ghr-ec2 override labels can request EC2 instance requirements that include GPU accelerator types.
ConcurrencyThe scale-up Lambda stops creating instances once the configured maximum number of runners is reached; an optional pool keeps a scheduled minimum of ephemeral org-level runners
Job limitsNot documented
Static IPsNot documented
SSH into running jobsYes
ObservabilityLambda and runner logs go to CloudWatch; Lambda tracing can be enabled and CloudWatch metrics are available as an experimental feature
SetupCreate and configure a GitHub App, download or build the Lambda artifacts, and deploy the module with Terraform. Then install the App on your organization or repositories.
Example label[self-hosted, linux]
PricingFree and open source; you pay for the infrastructure it runs on.
Free tierNot documented
ComplianceNot documented
RegionsNot documented
Open sourceYes (MIT)
Company headquartersNot documented

Facts from terraform-aws-github-runner’s public documentation, verified November 22, 2026. Performance figures are vendor claims.

Strengths and trade-offs

Reasons to choose it

  • You want runners on EC2 spot instances that scale down to zero when no workflows are active
  • You manage AWS with Terraform and want the whole runner stack defined as a module
  • You need Linux x64, Linux arm64 and Windows runners from one deployment through the multi-runner module
  • You want to bring your own AMI, instance types and subnets
  • You use GitHub Enterprise Server or GitHub Enterprise Cloud with data residency

Trade-offs

  • Enterprise-level runners are not supported; runners are registered at organization or repository level
  • The maintainers describe the project as maintained on a best-effort basis
  • The module states it is not certified by any security organisation and that example AMIs are not hardened
  • macOS runners, metrics and scale-set orchestration are marked experimental

Good fit for: Teams on AWS that manage infrastructure with Terraform and want GitHub Actions runners on EC2 that scale to zero.

Use cases terraform-aws-github-runner fits

  • Lower CI cost: Runners use EC2 spot instances by default and scale to zero when no workflows are active.
  • ARM64 builds: Graviton instance types are supported by setting the runner architecture to arm64.
  • Windows builds: Windows is a supported runner OS, with Windows Server 2022 as the default AMI.
  • Your own cloud: Runners are EC2 instances in your own VPC and subnets.
  • Open source and self-hosted: The module and its Lambda functions are MIT licensed and deployed entirely in your own AWS account.

How terraform-aws-github-runner compares

RunnerCI systemsRuns onDeploymentIsolationPriceLargest runnerDocker layer cacheGPUOpen sourceCompany HQ
terraform-aws-github-runnerGitHub ActionsLinux, Windows, macOS, x64, arm64Self-hostedEC2 instanceFree software + your infrastructureSet by your infrastructureNot documentedYesYesNot documented
Actions Runner Controller (ARC)GitHub ActionsLinux, WindowsSelf-hostedKubernetes podFree software + your infrastructureSet by your infrastructureNot documentedNot documentedYesUnited States
RunsOnGitHub ActionsLinux, Windows, x64, arm64Your cloud or hardwareEC2 instance€300/yr licence + AWS cost896 vCPUYesYesNoFrance
GARM (GitHub Actions Runner Manager)GitHub Actions, Forgejo/Gitea ActionsLinux, Windows, x64, arm64Self-hostedDepends on providerFree software + your infrastructureSet by your infrastructureNot documentedNot documentedYesRomania
AWS CodeBuild-hosted runnersGitHub Actions, GitLab CI, BuildkiteLinux, Windows, x64, arm64Your cloud accountFresh build environment$0.005/min72 vCPU / 144 GBYesYesNoUnited States
CirunGitHub ActionsLinux, macOS, Windows, x64, arm64Your cloud or hardwareCloud VM$29/mo (3 private repos) + cloud costSet by your infrastructureYesYesNoUnited Kingdom
HyperEnv for GitHub Actions RunnerGitHub ActionsLinux, x64Your cloud or hardwareEC2 instance$0.002/min fee + AWS cost192 vCPU / 768 GBNot documentedYesNoGermany
TestFlows GitHub Hetzner RunnersGitHub ActionsLinux, x64, arm64Self-hostedHetzner Cloud VMFree software + your infrastructureSet by your infrastructureYesNot documentedYesNot documented

Head-to-head: Actions Runner Controller (ARC) vs terraform-aws-github-runner · AWS CodeBuild-hosted runners vs terraform-aws-github-runner · Cirun vs terraform-aws-github-runner · GARM (GitHub Actions Runner Manager) vs terraform-aws-github-runner · HyperEnv for GitHub Actions Runner vs terraform-aws-github-runner · RunsOn vs terraform-aws-github-runner · terraform-aws-github-runner vs TestFlows GitHub Hetzner Runners · ec2-github-runner vs terraform-aws-github-runner

See all terraform-aws-github-runner alternatives →

Frequently asked questions

What is terraform-aws-github-runner?
Terraform module that runs GitHub Actions runners on EC2 spot or on-demand instances, scaled by Lambda functions. A community-maintained Terraform module for webhook-driven GitHub Actions runners on EC2; it suits AWS teams that are comfortable operating Lambda, SQS and Terraform themselves.
Which CI systems does terraform-aws-github-runner work with?
terraform-aws-github-runner runs jobs for GitHub Actions, on Linux, Windows, macOS, x64 and arm64.
How does terraform-aws-github-runner isolate jobs?
terraform-aws-github-runner documents its isolation as: Each runner is an EC2 instance in your AWS account; by default runners are reused until they are idle, and in ephemeral mode each instance takes one job with a just-in-time configuration and is then terminated.
Is terraform-aws-github-runner open source?
Yes (MIT). It can be self-hosted.
How much does terraform-aws-github-runner cost?
Free and open source; you pay for the infrastructure it runs on. Check the official pricing page for current rates.
How do you set up terraform-aws-github-runner?
Create and configure a GitHub App, download or build the Lambda artifacts, and deploy the module with Terraform. Then install the App on your organization or repositories. An example label is [self-hosted, linux].
Does terraform-aws-github-runner support ARM64 runners?
Yes, terraform-aws-github-runner documents arm64 runners (Linux, Windows and macOS).
Does terraform-aws-github-runner offer macOS runners?
Yes, terraform-aws-github-runner documents macOS runners alongside Linux and Windows.
Does terraform-aws-github-runner offer GPU runners?
With dynamic labels enabled, ghr-ec2 override labels can request EC2 instance requirements that include GPU accelerator types.
How many jobs can run at once on terraform-aws-github-runner?
The scale-up Lambda stops creating instances once the configured maximum number of runners is reached; an optional pool keeps a scheduled minimum of ephemeral org-level runners.
What are the alternatives to terraform-aws-github-runner?

Sources

  1. github.com/github-aws-runners/terraform-aws-github-runner
  2. github.com/github-aws-runners/terraform-aws-github-runner/releases
  3. github.com/github-aws-runners/terraform-aws-github-runner/blob/main/CHANGELOG.md
  4. github.com/github-aws-runners/terraform-aws-github-runner/blob/main/LICENSE.md
  5. github-aws-runners.github.io/terraform-aws-github-runner/
  6. github-aws-runners.github.io/terraform-aws-github-runner/getting-started/
  7. github-aws-runners.github.io/terraform-aws-github-runner/configuration/
  8. github-aws-runners.github.io/terraform-aws-github-runner/security/

Check before you rely on it. Products change quickly, and this page reflects public documentation as of November 22, 2026. Confirm anything that matters in the provider’s own documentation.

Cite this page

CI Runners. (2026). terraform-aws-github-runner. cirunners.org. Last reviewed November 22, 2026. https://cirunners.org/runners/terraform-aws-github-runner/