terraform-aws-gitlab-runner
Terraform module that deploys GitLab Runner on AWS and autoscales its job workers on EC2 spot instances. A community Terraform module for autoscaling GitLab Runner on AWS spot instances; it suits GitLab teams that already manage AWS with Terraform.
Overview
terraform-aws-gitlab-runner is a community Terraform module that creates a GitLab Runner deployment on AWS. A runner agent runs on one EC2 instance and starts worker instances for builds, on spot instances by default, using the docker+machine executor. The module registers the agent automatically, streams logs to CloudWatch, and creates an S3 bucket as a shared cache with lifecycle rules.
The README describes three scenarios: one agent that autoscales workers, several agents created by instantiating the module more than once, and a plain Docker runner without autoscaling. A newer scenario uses GitLab’s Docker Autoscaler executor in place of Docker Machine and needs a worker AMI with Docker Engine preinstalled. Scheduled scaling, a Lambda function for graceful termination and Session Manager access to instances are included. The module is published in the Terraform Registry.
Notable
- Version 9.6.0 was released on 9 October 2026
- The README traces the module to a 2017 blog post on running GitLab runners on spot instances
terraform-aws-gitlab-runner specifications
| Attribute | Details |
|---|---|
| CI systems | GitLab CI |
| Operating systems | Linux |
| Architectures | Not documented |
| Deployment | Open-source project |
| Where it can run | AWS |
| Isolation | A runner agent on one EC2 instance creates worker EC2 instances with the docker+machine executor (the default) or the Docker Autoscaler executor; in the plain docker scenario builds run on the agent instance itself |
| Fresh environment per job | Not documented |
| Hardware | EC2 instances, spot by default; a spot fleet scenario spreads workers over several instance types and availability zones |
| Performance (vendor claim) | Not documented |
| Runner sizes | Not documented |
| Caching | Creates an S3 bucket as a shared runner cache by default, with a lifecycle policy that removes old objects; the bucket can be managed outside the module to share it between runners. |
| Docker layer caching | Not documented |
| GPU | Not documented |
| Concurrency | Not documented |
| Job limits | Not documented |
| Static IPs | Not documented |
| SSH into running jobs | Yes |
| Observability | Runner logs are streamed to CloudWatch |
| Setup | Store a pre-registered GitLab runner token in an SSM parameter and apply the Terraform module with your VPC and subnet settings. |
| Example label | Not documented |
| 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-gitlab-runner’s public documentation, verified November 22, 2026. Performance figures are vendor claims.
Strengths and trade-offs
Reasons to choose it
- You use GitLab CI and want runners on EC2 spot instances defined in Terraform
- You want an S3-backed shared cache created for you
- You want to run several runner agents with different configurations from the same module
- You want to move from Docker Machine to the Docker Autoscaler executor within the same module
Trade-offs
- The default docker+machine executor depends on Docker Machine, which the usage guide notes is no longer maintained by Docker
- The Docker Autoscaler scenario needs an AMI with Docker Engine preinstalled, which base Amazon Linux and Ubuntu AMIs do not have
- The plain docker scenario does not support auto-scaling
- Removing the module requires a specific procedure so that key pairs and spot requests are cleaned up
Good fit for: Teams on GitLab CI that manage AWS with Terraform and want autoscaling runners on spot instances.
Use cases terraform-aws-gitlab-runner fits
- Lower CI cost: Workers run on EC2 spot instances by default.
- Your own cloud: All instances, the cache bucket and the Lambda functions are created in your own AWS account.
- Open source and self-hosted: The module is MIT licensed and published in the Terraform Registry.
- GitLab CI runners: The module deploys and registers GitLab Runner agents and their autoscaled workers.
How terraform-aws-gitlab-runner compares
| Runner | CI systems | Runs on | Deployment | Isolation | Price | Largest runner | Docker layer cache | GPU | Open source | Company HQ |
|---|---|---|---|---|---|---|---|---|---|---|
| terraform-aws-gitlab-runner | GitLab CI | Linux | Self-hosted | EC2 instance | Free software + your infrastructure | Set by your infrastructure | Not documented | Not documented | Yes | Not documented |
| GitLab Runner | GitLab CI | Linux, macOS, Windows, x64, arm64 | Self-hosted | Depends on executor | Free software + your infrastructure | Set by your infrastructure | Not documented | Yes | Yes | Not documented |
| GitLab-hosted runners | GitLab CI | Linux, macOS, Windows, x64, arm64 | Platform-hosted | Ephemeral VM | $10 per 1,000 compute minutes | 32 vCPU / 128 GB | Not documented | Yes | No | 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 |
| Elastic CI Stack for AWS | Buildkite | Linux, Windows, x64, arm64 | Self-hosted | EC2 instance | Free software + your infrastructure | Set by your infrastructure | Not documented | Not documented | Yes | Australia |
| 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 |
Head-to-head: GitLab Runner vs terraform-aws-gitlab-runner
Frequently asked questions
What is terraform-aws-gitlab-runner?
Which CI systems does terraform-aws-gitlab-runner work with?
How does terraform-aws-gitlab-runner isolate jobs?
Is terraform-aws-gitlab-runner open source?
How much does terraform-aws-gitlab-runner cost?
How do you set up terraform-aws-gitlab-runner?
What are the alternatives to terraform-aws-gitlab-runner?
Sources
- github.com/cattle-ops/terraform-aws-gitlab-runner
- github.com/cattle-ops/terraform-aws-gitlab-runner/releases
- github.com/cattle-ops/terraform-aws-gitlab-runner/blob/main/docs/usage.md
- github.com/cattle-ops/terraform-aws-gitlab-runner/blob/main/CHANGELOG.md
- github.com/cattle-ops/terraform-aws-gitlab-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). terraform-aws-gitlab-runner. cirunners.org. Last reviewed November 22, 2026. https://cirunners.org/runners/terraform-aws-gitlab-runner/