CI Runnerscirunners.org
Runner profile · Open-source project

terraform-aws-gitlab-runner

Answer in brief

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.

By the CI Runners editors · Updated

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

AttributeDetails
CI systemsGitLab CI
Operating systemsLinux
ArchitecturesNot documented
DeploymentOpen-source project
Where it can runAWS
IsolationA 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 jobNot documented
HardwareEC2 instances, spot by default; a spot fleet scenario spreads workers over several instance types and availability zones
Performance (vendor claim)Not documented
Runner sizesNot documented
CachingCreates 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 cachingNot documented
GPUNot documented
ConcurrencyNot documented
Job limitsNot documented
Static IPsNot documented
SSH into running jobsYes
ObservabilityRunner logs are streamed to CloudWatch
SetupStore a pre-registered GitLab runner token in an SSM parameter and apply the Terraform module with your VPC and subnet settings.
Example labelNot documented
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 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

RunnerCI systemsRuns onDeploymentIsolationPriceLargest runnerDocker layer cacheGPUOpen sourceCompany HQ
terraform-aws-gitlab-runnerGitLab CILinuxSelf-hostedEC2 instanceFree software + your infrastructureSet by your infrastructureNot documentedNot documentedYesNot documented
GitLab RunnerGitLab CILinux, macOS, Windows, x64, arm64Self-hostedDepends on executorFree software + your infrastructureSet by your infrastructureNot documentedYesYesNot documented
GitLab-hosted runnersGitLab CILinux, macOS, Windows, x64, arm64Platform-hostedEphemeral VM$10 per 1,000 compute minutes32 vCPU / 128 GBNot documentedYesNoNot documented
terraform-aws-github-runnerGitHub ActionsLinux, Windows, macOS, x64, arm64Self-hostedEC2 instanceFree software + your infrastructureSet by your infrastructureNot documentedYesYesNot documented
Elastic CI Stack for AWSBuildkiteLinux, Windows, x64, arm64Self-hostedEC2 instanceFree software + your infrastructureSet by your infrastructureNot documentedNot documentedYesAustralia
AWS CodeBuild-hosted runnersGitHub Actions, GitLab CI, BuildkiteLinux, Windows, x64, arm64Your cloud accountFresh build environment$0.005/min72 vCPU / 144 GBYesYesNoUnited States

Head-to-head: GitLab Runner vs terraform-aws-gitlab-runner

See all terraform-aws-gitlab-runner alternatives →

Frequently asked questions

What is 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.
Which CI systems does terraform-aws-gitlab-runner work with?
terraform-aws-gitlab-runner runs jobs for GitLab CI, on Linux.
How does terraform-aws-gitlab-runner isolate jobs?
terraform-aws-gitlab-runner documents its isolation as: 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.
Is terraform-aws-gitlab-runner open source?
Yes (MIT). It can be self-hosted.
How much does terraform-aws-gitlab-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 terraform-aws-gitlab-runner?
Store a pre-registered GitLab runner token in an SSM parameter and apply the Terraform module with your VPC and subnet settings.
What are the alternatives to terraform-aws-gitlab-runner?

Sources

  1. github.com/cattle-ops/terraform-aws-gitlab-runner
  2. github.com/cattle-ops/terraform-aws-gitlab-runner/releases
  3. github.com/cattle-ops/terraform-aws-gitlab-runner/blob/main/docs/usage.md
  4. github.com/cattle-ops/terraform-aws-gitlab-runner/blob/main/CHANGELOG.md
  5. 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/