Scaling Gitlab Runners in AWS using Docker autoscaler

CI/CD has become essential in modern software development. Automated builds, testing, and deployments allow teams to ship applications faster and more reliably. One of the most popular CI/CD platforms today is GitLab.

GitLab provides two types of runners:

• Managed runners — hosted and managed by GitLab
• Self-hosted runners — managed within our infrastructure

Self-hosted runners allow us to:

• Run builds within their own network
• Access internal services and repositories
• Maintain full control over compute resources
• Optimize cost and performance

In this article, we will focus on self-hosted GitLab runners and how to scale them automatically in AWS using the Docker Autoscaler.

Architecture

Setting up a simple VM GitLab runner involves two main steps:

1. Install GitLab Runner
2. Register the runner with GitLab

However, running all builds on a single VM can become a bottleneck when multiple pipelines run simultaneously.

A better approach is to scale runners dynamically based on demand.

Get Sajan K’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

In this setup we have two components —
- Runner managers — A dedicated instance that manages runner orchestration.
- Runner workers — Instances that actually execute the CI jobs inside Docker containers.

Installation & Configuration

1. Create an instance gitlab-runner in AWS. This will be your gitlab runner manager
2. Install GitLab Runner on the instance.
3. Register the runner
4. Create ssh key pair in gitlab-runner user. This is for communication with gitlab runner workers. Mostly will be saved in /home/gitlab-worker/.ssh/directory.

ssh-keygen -t rsa -b 4096

5. Create AMI for gitlab runner workers.
a. Create an instance gitlab-worker in AWS
b. Create a user gitlab

useradd -m gitlab

c. Install docker for docker executer in runner-worker

## For RHEL
dnf -y install dnf-plugins-core

sudo dnf config-manager \
  --add-repo https://download.docker.com/linux/rhel/docker-ce.repo

sudo dnf install docker-ce docker-ce-cli \
  containerd.io docker-buildx-plugin docker-compose-plugin

d. Give permission for gitlab user to execute docker commands.

usermod -aG docker gitlab

e. To conigure SSH access from gitlab manager to gitlab workers, copy the ssh public key generated (step 4) in gitlab-manager to authorized keys file — /home/gitlab/.ssh/authorized_keys in gitlab-worker.

f. Create an AMI gitlab-worker-amifrom gitlab-worker. You can terminate the gitlab-worker instance once AMI creation is completed

6. Create an autoscaling group in AWS gitlab-worker . This autoscaling group should use a launch template having gitlab-worker-ami which we created earlier. Set the Desired and minimum capacity as 0. Maximum you can set as per the build jobs. Lets keep it 5 for now.

7. Now coming back to gitlab runner manager. Configure gitlab runner manager for auto scaling by adding this in /etc/gitlab-runner/config.toml . I have given the explanation as comments. For more options and information please read the official documentation.

  [runners.autoscaler]
    plugin = "aws:latest"   #### Plugin for aws autoscaling ###
    capacity_per_instance = 1 ### The number of concurrent jobs a single EC2 instance is allowed to run at the same time. ###
    max_use_count = 1 ### The total number of jobs an instance can process before it is automatically terminated. ###
    max_instances = 5 ### The hard limit on the total number of AWS instances this runner is allowed to create. ###
    [runners.autoscaler.plugin_config]
      name             = "gitlab-worker" ### Name of the autoscaling group ###
    [runners.autoscaler.connector_config]
      username               = "gitlab" ### user which gitlab manager ssh to gitlab worker ###
      use_external_addr      = false ### use private IP ###
      use_static_credentials = true 
      key_path               = "/home/gitlab-runner/.ssh/id_rsa"
      timeout                = "5m"

8. The Docker Autoscaler uses fleeting plugins to autoscale. So install it -

gitlab-runner fleeting install

9. Start gitlab-runner in gitlab-manager and ensures it is registered.

systemctl gitlab-runner start

10. Run a gitlab ci job tagging your runner and see gitlab-worker coming up and doing its job.

Conclusion

Running scalable CI infrastructure for a medium job traffic doesn’t necessarily require Kubernetes. With GitLab Runner Docker Autoscaler and AWS, you can build a simple, scalable, and cost-efficient CI system using just virtual machines.

Try this out and let me know if you have any questions.