How to Autoscale GitHub Runners on AWS EC2 With Terraform

The philips-labs Terraform module launches ephemeral EC2 runners in response to workflow_job webhooks and scales them down when idle.

The philips-labs/terraform-aws-github-runner module wires a GitHub App webhook to Lambda functions that launch ephemeral EC2 instances per queued job and terminate them after. It supports spot instances, pools, and scale-to-zero, so you get on-demand runners without managing servers.

Steps

• Create a GitHub App and configure the workflow_job webhook.
• Point the module at your VPC subnets and the App credentials.
• Enable enable_ephemeral_runners so each instance runs one job then terminates.

main.tf

module "runners" {
  source  = "philips-labs/github-runner/aws"

  aws_region = "us-east-1"
  vpc_id     = var.vpc_id
  subnet_ids = var.private_subnets

  github_app = {
    key_base64     = var.github_app_key_base64
    id             = var.github_app_id
    webhook_secret = var.webhook_secret
  }

  runner_extra_labels     = ["ephemeral", "linux"]
  enable_ephemeral_runners = true
  instance_types          = ["m5.large"]
}

Gotchas

• Ephemeral runners require the workflow_job webhook so the scale-up Lambda fires per job.
• Give the module private subnets with a NAT so runners reach GitHub without public IPs.

Related guides