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.
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
| Attribute | Details |
|---|---|
| CI systems | GitHub Actions |
| Operating systems | Linux, Windows, macOS |
| Architectures | x64, arm64 |
| Deployment | Open-source project |
| Where it can run | AWS |
| Isolation | 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 |
| Fresh environment per job | Not documented |
| Hardware | EC2 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 sizes | Not documented |
| Caching | Not documented |
| Docker layer caching | Not documented |
| GPU | With dynamic labels enabled, ghr-ec2 override labels can request EC2 instance requirements that include GPU accelerator types. |
| Concurrency | 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 |
| Job limits | Not documented |
| Static IPs | Not documented |
| SSH into running jobs | Yes |
| Observability | Lambda and runner logs go to CloudWatch; Lambda tracing can be enabled and CloudWatch metrics are available as an experimental feature |
| Setup | 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. |
| Example label | [self-hosted, linux] |
| Pricing | Free and open source; you pay for the infrastructure it runs on. |
| Free tier | Not documented |
| Compliance | Not documented |
| Regions | Not documented |
| Open source | Yes (MIT) |
| Company headquarters | Not 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
| Runner | CI systems | Runs on | Deployment | Isolation | Price | Largest runner | Docker layer cache | GPU | Open source | Company HQ |
|---|---|---|---|---|---|---|---|---|---|---|
| terraform-aws-github-runner | GitHub Actions | Linux, Windows, macOS, x64, arm64 | Self-hosted | EC2 instance | Free software + your infrastructure | Set by your infrastructure | Not documented | Yes | Yes | Not documented |
| Actions Runner Controller (ARC) | GitHub Actions | Linux, Windows | Self-hosted | Kubernetes pod | Free software + your infrastructure | Set by your infrastructure | Not documented | Not documented | Yes | United States |
| RunsOn | GitHub Actions | Linux, Windows, x64, arm64 | Your cloud or hardware | EC2 instance | €300/yr licence + AWS cost | 896 vCPU | Yes | Yes | No | France |
| GARM (GitHub Actions Runner Manager) | GitHub Actions, Forgejo/Gitea Actions | Linux, Windows, x64, arm64 | Self-hosted | Depends on provider | Free software + your infrastructure | Set by your infrastructure | Not documented | Not documented | Yes | Romania |
| AWS CodeBuild-hosted runners | GitHub Actions, GitLab CI, Buildkite | Linux, Windows, x64, arm64 | Your cloud account | Fresh build environment | $0.005/min | 72 vCPU / 144 GB | Yes | Yes | No | United States |
| Cirun | GitHub Actions | Linux, macOS, Windows, x64, arm64 | Your cloud or hardware | Cloud VM | $29/mo (3 private repos) + cloud cost | Set by your infrastructure | Yes | Yes | No | United Kingdom |
| HyperEnv for GitHub Actions Runner | GitHub Actions | Linux, x64 | Your cloud or hardware | EC2 instance | $0.002/min fee + AWS cost | 192 vCPU / 768 GB | Not documented | Yes | No | Germany |
| TestFlows GitHub Hetzner Runners | GitHub Actions | Linux, x64, arm64 | Self-hosted | Hetzner Cloud VM | Free software + your infrastructure | Set by your infrastructure | Yes | Not documented | Yes | Not 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
Frequently asked questions
What is terraform-aws-github-runner?
Which CI systems does terraform-aws-github-runner work with?
How does terraform-aws-github-runner isolate jobs?
Is terraform-aws-github-runner open source?
How much does terraform-aws-github-runner cost?
How do you set up terraform-aws-github-runner?
[self-hosted, linux].Does terraform-aws-github-runner support ARM64 runners?
Does terraform-aws-github-runner offer macOS runners?
Does terraform-aws-github-runner offer GPU runners?
How many jobs can run at once on terraform-aws-github-runner?
What are the alternatives to terraform-aws-github-runner?
Sources
- github.com/github-aws-runners/terraform-aws-github-runner
- github.com/github-aws-runners/terraform-aws-github-runner/releases
- github.com/github-aws-runners/terraform-aws-github-runner/blob/main/CHANGELOG.md
- github.com/github-aws-runners/terraform-aws-github-runner/blob/main/LICENSE.md
- github-aws-runners.github.io/terraform-aws-github-runner/
- github-aws-runners.github.io/terraform-aws-github-runner/getting-started/
- github-aws-runners.github.io/terraform-aws-github-runner/configuration/
- 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/