CI Runnerscirunners.org
Runner profile · Open-source project

ec2-github-runner

Answer in brief

GitHub Action that starts an EC2 instance as a self-hosted runner at the start of a workflow and terminates it at the end. A GitHub Action that launches and removes one EC2 runner per workflow run; it suits repositories with occasional needs for custom hardware or VPC access rather than a shared runner fleet.

By the CI Runners editors · Updated

Overview

ec2-github-runner is a GitHub Action rather than a standing service. In the documented workflow, a first job on a GitHub-hosted runner calls the action in start mode to launch an EC2 instance and register it as a self-hosted runner with a unique label. The main job runs on that label. A final job calls the action in stop mode to terminate the instance and remove the runner. Everything is driven from the workflow file.

The README gives three uses: reaching private resources in a VPC, picking any EC2 instance type, and saving cost. Inputs cover the AMI, subnet, security group, IAM role, spot market type, block devices and a pre-runner script. A JIT option registers a single-use runner, and a multi-AZ option tries several subnets or regions in turn. Runners are registered at repository level with a personal access token.

Notable

  • v2.6.1 was released on 10 April 2026
  • The README documents JIT runners, multi-AZ failover and a debug mode as advanced options

ec2-github-runner specifications

AttributeDetails
CI systemsGitHub Actions
Operating systemsLinux
ArchitecturesNot documented
DeploymentOpen-source project
Where it can runAWS
IsolationEach workflow run starts its own EC2 instance in your VPC and a stop job terminates it; with the optional JIT mode the runner is single-use and deregisters after one job
Fresh environment per jobNot documented
HardwareAny EC2 instance type, on-demand or spot, from an AMI you provide
Performance (vendor claim)Not documented
Runner sizesNot documented
CachingNot documented
Docker layer cachingNot documented
GPUNot documented
ConcurrencyNot documented
Job limitsNot documented
Static IPsNot documented
SSH into running jobsNot documented
ObservabilityAn optional debug mode streams the EC2 serial console output into the GitHub Actions log during runner startup
SetupAdd a start job and a stop job that call machulav/ec2-github-runner@v2 with AWS credentials, a GitHub personal access token, an AMI, a subnet and a security group. The job in between uses the label output as its runs-on value.
Example label${{ needs.start-runner.outputs.label }}
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 ec2-github-runner’s public documentation, verified November 22, 2026. Performance figures are vendor claims.

Strengths and trade-offs

Reasons to choose it

  • You want an EC2 runner that exists only for the duration of one workflow
  • You need a job to reach private resources in your VPC
  • You want to pick the EC2 instance type per workflow, on-demand or spot
  • You do not want to deploy and operate webhooks, Lambda functions or a controller

Trade-offs

  • The workflow must include a stop job; otherwise the EC2 instance keeps running after the workflow finishes
  • It needs a GitHub personal access token with the repo scope and manages runners at repository level
  • You must prepare an AMI with Docker and Git installed, or install them at boot
  • The README repeats GitHub’s recommendation not to use self-hosted runners with public repositories

Good fit for: Repositories that occasionally need a job to run on a specific EC2 instance type or inside a private VPC, without operating a standing autoscaler.

Use cases ec2-github-runner fits

  • Lower CI cost: The README describes running jobs on cheaper EC2 instances, including spot, as one of its uses.
  • Your own cloud: The runner is an EC2 instance in a subnet and security group that you choose.
  • Open source and self-hosted: The action is MIT licensed and runs from your own workflow.

How ec2-github-runner compares

RunnerCI systemsRuns onDeploymentIsolationPriceLargest runnerDocker layer cacheGPUOpen sourceCompany HQ
ec2-github-runnerGitHub ActionsLinuxSelf-hostedEC2 instanceFree software + your infrastructureSet by your infrastructureNot documentedNot documentedYesNot documented
terraform-aws-github-runnerGitHub ActionsLinux, Windows, macOS, x64, arm64Self-hostedEC2 instanceFree software + your infrastructureSet by your infrastructureNot documentedYesYesNot documented
RunsOnGitHub ActionsLinux, Windows, x64, arm64Your cloud or hardwareEC2 instance€300/yr licence + AWS cost896 vCPUYesYesNoFrance
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
Actions Runner Controller (ARC)GitHub ActionsLinux, WindowsSelf-hostedKubernetes podFree software + your infrastructureSet by your infrastructureNot documentedNot documentedYesUnited States
HyperEnv for GitHub Actions RunnerGitHub ActionsLinux, x64Your cloud or hardwareEC2 instance$0.002/min fee + AWS cost192 vCPU / 768 GBNot documentedYesNoGermany

Head-to-head: ec2-github-runner vs terraform-aws-github-runner

See all ec2-github-runner alternatives →

Frequently asked questions

What is ec2-github-runner?
GitHub Action that starts an EC2 instance as a self-hosted runner at the start of a workflow and terminates it at the end. A GitHub Action that launches and removes one EC2 runner per workflow run; it suits repositories with occasional needs for custom hardware or VPC access rather than a shared runner fleet.
Which CI systems does ec2-github-runner work with?
ec2-github-runner runs jobs for GitHub Actions, on Linux.
How does ec2-github-runner isolate jobs?
ec2-github-runner documents its isolation as: Each workflow run starts its own EC2 instance in your VPC and a stop job terminates it; with the optional JIT mode the runner is single-use and deregisters after one job.
Is ec2-github-runner open source?
Yes (MIT). It can be self-hosted.
How much does ec2-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 ec2-github-runner?
Add a start job and a stop job that call machulav/ec2-github-runner@v2 with AWS credentials, a GitHub personal access token, an AMI, a subnet and a security group. The job in between uses the label output as its runs-on value. An example label is ${{ needs.start-runner.outputs.label }}.
What are the alternatives to ec2-github-runner?

Sources

  1. github.com/machulav/ec2-github-runner
  2. github.com/machulav/ec2-github-runner/releases
  3. github.com/machulav/ec2-github-runner/blob/main/LICENSE

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). ec2-github-runner. cirunners.org. Last reviewed November 22, 2026. https://cirunners.org/runners/ec2-github-runner/