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.
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
| Attribute | Details |
|---|---|
| CI systems | GitHub Actions |
| Operating systems | Linux |
| Architectures | Not documented |
| Deployment | Open-source project |
| Where it can run | AWS |
| Isolation | 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 |
| Fresh environment per job | Not documented |
| Hardware | Any EC2 instance type, on-demand or spot, from an AMI you provide |
| Performance (vendor claim) | Not documented |
| Runner sizes | Not documented |
| Caching | Not documented |
| Docker layer caching | Not documented |
| GPU | Not documented |
| Concurrency | Not documented |
| Job limits | Not documented |
| Static IPs | Not documented |
| SSH into running jobs | Not documented |
| Observability | An optional debug mode streams the EC2 serial console output into the GitHub Actions log during runner startup |
| Setup | 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. |
| Example label | ${{ needs.start-runner.outputs.label }} |
| 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 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
| Runner | CI systems | Runs on | Deployment | Isolation | Price | Largest runner | Docker layer cache | GPU | Open source | Company HQ |
|---|---|---|---|---|---|---|---|---|---|---|
| ec2-github-runner | GitHub Actions | Linux | Self-hosted | EC2 instance | Free software + your infrastructure | Set by your infrastructure | Not documented | Not documented | Yes | Not documented |
| 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 |
| RunsOn | GitHub Actions | Linux, Windows, x64, arm64 | Your cloud or hardware | EC2 instance | €300/yr licence + AWS cost | 896 vCPU | Yes | Yes | No | France |
| 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 |
| 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 |
| 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 |
Head-to-head: ec2-github-runner vs terraform-aws-github-runner
Frequently asked questions
What is ec2-github-runner?
Which CI systems does ec2-github-runner work with?
How does ec2-github-runner isolate jobs?
Is ec2-github-runner open source?
How much does ec2-github-runner cost?
How do you set up ec2-github-runner?
${{ needs.start-runner.outputs.label }}.What are the alternatives to ec2-github-runner?
Sources
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/