How To Autoscale GitLab Continuous Deployment with GitLab Runner on DigitalOcean

Updated on June 19, 2018

Owen Williams

How To Autoscale GitLab Continuous Deployment with GitLab Runner on DigitalOcean


GitLab is an open-source tool used by software teams to manage their complete development and delivery lifecycle. GitLab provides a broad set of functionality: issue tracking, git repositories, continuous integration, container registry, deployment, and monitoring. These features are all built from the ground up as a single application. You can host GitLab on your own servers or use GitLab.com, a cloud service where open-source projects get all the top-tier features for free.

GitLab’s continuous integration / continuous delivery (CI/CD) functionality is an effective way to build the habit of testing all code before it’s deployed. GitLab CI/CD is also highly scalable thanks to an additional tool, GitLab Runner, which automates scaling your build queue in order to avoid long wait times for development teams trying to release code.

In this guide, we will demonstrate how to configure a highly scalable GitLab infrastructure that manages its own costs, and automatically responds to load by increasing and decreasing available server capacity.


We’re going to build a scalable CI/CD process on DigitalOcean that automatically responds to demand by creating new servers on the platform and destroys them when the queue is empty.

These reusable servers are spawned by the GitLab Runner process and are automatically deleted when no jobs are running, reducing costs and administration overhead for your team.

As we’ll explain in this tutorial, you are in control of how many machines are created at any given time, as well as the length of time they’re retained before being destroyed.

We’ll be using three separate servers to build this project, so let’s go over terminology first:

  • GitLab: Your hosted GitLab instance or self-hosted instance where your code repositories are stored.

  • GitLab Bastion: The bastion server or Droplet is the core of what we’ll be configuring. It is the control instance that is used to interact with the DigitalOcean API to create Droplets and destroy them when necessary. No jobs are executed on this server.

  • GitLab Runners: Your runners are transient servers or Droplets that are created on the fly by the bastion server when needed to execute a CI/CD job in your build queue. These servers are disposable, and are where your code is executed or tested before your build is marked as passing or failing.

GitLab Runners Diagram

By leveraging each of the GitLab components, the CI/CD process will enable you to scale responsively based on demands. With these goals in mind, we are ready to begin setting up our continuous deployment with GitLab and DigitalOcean.


This tutorial will assume you have already configured GitLab on your own server or through the hosted service, and that you have an existing DigitalOcean account.

To set this up on an Ubuntu 16.04 Droplet, you can use the DigitalOcean one-click image, or follow our guide: “How To Install and Configure GitLab on Ubuntu 16.04.”

For the purposes of this tutorial, we assume you have private networking enabled on this Droplet, which you can achieve by following our guide on “How To Enable DigitalOcean Private Networking on Existing Droplets,” but it is not compulsory.

Throughout this tutorial, we’ll be using non-root users with admin privileges on our Droplets.

Step 1 — Import JavaScript Project

To begin, we will create a new example project in your existing GitLab instance containing a sample Node.js application.

GitLab Interface

Login to your GitLab instance and click the plus icon, then select New project from the dropdown menu.

On the new project screen, select the Import project tag, then click Repo by URL to import our example project directly from GitHub.

Paste the below clone URL into the Git repository URL:


This repository is a basic JavaScript application for the purposes of demonstration, which we won’t be running in production. To complete the import, click the New Project button.

Your new project will now be in GitLab and we can get started setting up our CI pipeline.

Step 2 — Set Up Infrastructure

Our GitLab Code Runner requires specific configuration as we’re planning to programmatically create Droplets to handle CI load as it grows and shrinks.

We will create two types of machines in this tutorial: a bastion instance, which controls and spawns new machines, and our runner instances, which are temporary servers spawned by the bastion Droplet to build code when required. The bastion instance uses Docker to create your runners.

Here are the DigitalOcean products we’ll use, and what each component is used for:

  • Flexible Droplets — We will create memory-optimized Droplets for our GitLab Runners as it’s a memory-intensive process which will run using Docker for containerization. You can shrink or grow this Droplet in the future as needed, however we recommend the flexible Droplet option as a starting point to understand how your pipeline will perform under load.

  • DigitalOcean Spaces (Object Storage) — We will use DigitalOcean Spaces to persist cached build components across your runners as they’re created and destroyed. This reduces the time required to set up a new runner when the CI pipeline is busy, and allows new runners to pick up where others left off immediately.

  • Private Networking — We will create a private network for your bastion Droplet and GitLab runners to ensure secure code compilation and to reduce firewall configuration required.

To start, we’ll create the bastion Droplet. Create a new Droplet, then under choose an image, select the One-click apps tab. From there, select Docker 17.12.0-ce on 16.04 (note that this version is current at the time of writing), then choose the smallest Droplet size available, as our bastion Droplet will manage the creation of other Droplets rather than actually perform tests.

It is recommended that you create your server in a data center that includes DigitalOcean Spaces in order to use the object storage caching features mentioned earlier.

Select both the Private networking and Monitoring options, then click Create Droplet.

We also need to set up our storage space which will be used for caching. Follow the steps in “How To Create a DigitalOcean Space and API Key” to create a new Space in the same or nearest data center as your hosted GitLab instance, along with an API Key.

Note this key down, as we’ll need it later in the tutorial.

Now it’s time to get our CI started!

Step 3 — Configure the GitLab Runner Bastion Server

With the fresh Droplet ready, we can now configure GitLab Runner. We’ll be installing scripts from GitLab and GitHub repositories.

As a best practice, be sure to inspect scripts to confirm what you will be installing prior to running the full commands below.

Connect to the Droplet using SSH, move into the /tmp directory, then add the official GitLab Runner repository to Ubuntu’s package manager:

  1. cd /tmp
  2. curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

Once added, install the GitLab Runner application:

  1. sudo apt-get install gitlab-runner

We also need to install Docker Machine, which is an additional Docker tool that assists with automating the deployment of containers on cloud providers:

  1. curl -L https://github.com/docker/machine/releases/download/v0.14.0/docker-machine-`uname -s`-`uname -m` >/tmp/docker-machine && \
  2. sudo install /tmp/docker-machine /usr/local/bin/docker-machine

With these installations complete, we can move on to connecting our GitLab Runner to our GitLab install.

Step 4 — Obtain Runner Registration Token

To link GitLab Runner to your existing GitLab install, we need to link the two instances together by obtaining a token that authenticates your runner to your code repositories.

Login to your existing GitLab instance as the admin user, then click the wrench icon to enter the admin settings area.

On the left of your screen, hover over Overview and select Runners from the list that appears.

On the Runners page under the How to setup a shared Runner for a new project section, copy the token shown in Step 3, and make a note of it along with the publicly accessible URL of your GitLab instance from Step 2. If you are using HTTPS for Gitlab, make sure it is not a self-signed certificate, or GitLab Runner will fail to start.

Step 5 — Configure GitLab on the Bastion Droplet

Back in your SSH connection with your bastion Droplet, run the following command:

  1. sudo gitlab-runner register

This will initiate the linking process, and you will be asked a series of questions.

On the next step, enter the GitLab instance URL from the previous step:

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com)

Enter the token you obtained from your GitLab instance:

Please enter the gitlab-ci token for this runner

Enter a description that will help you recognize it in the GitLab web interface. We recommend naming this instance something unique, like runner-bastion for clarity.

Please enter the gitlab-ci description for this runner
[yourhostname] runner-bastion

If relevant, you may enter the tags for code you will build with your runner. However, we recommend this is left blank at this stage. This can easily be changed from the GitLab interface later.

Please enter the gitlab-ci tags for this runner (comma separated):

Choose whether or not your runner should be able to run untagged jobs. This setting allows you to choose whether your runner should build repositories with no tags at all, or require specific tags. Select true in this case, so your runner can execute all repositories.

Whether to run untagged jobs [true/false]: true

Choose if this runner should be shared among your projects, or locked to the current one, which blocks it from building any code other than those specified. Select false for now, as this can be changed later in GitLab’s interface:

Whether to lock Runner to current project [true/false]: false

Choose the executor which will build your machines. Because we’ll be creating new Droplets using Docker, we’ll choose docker+machine here, but you can read more about the advantages of each approach in this compatibility chart:

Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell:

You’ll be asked which image to use for projects that don’t explicitly define one. We’ll choose a basic, secure default:

Please enter the Docker image (e.g. ruby:2.1):

Now you’re done configuring the core bastion runner! At this point it should appear within the GitLab Runner page of your GitLab admin settings, which we accessed to obtain the token.

If you encounter any issues with these steps, the GitLab Runner documentation includes options for troubleshooting.

Step 6 — Configure Docker Caching and Docker Machine

To speed up Droplet creation when the build queue is busy, we’ll leverage Docker’s caching tools on the Bastion Droplet to store the images for your commonly used containers on DigitalOcean Spaces.

To do so, upgrade Docker Machine on your SSH shell using the following command:

  1. curl -L https://github.com/docker/machine/releases/download/v0.14.0/docker-machine-`uname -s`-`uname -m` >/tmp/docker-machine && sudo install /tmp/docker-machine /usr/local/bin/docker-machine

With Docker Machine upgraded, we can move on to setting up our access tokens for GitLab Runner to use.

Step 7 — Gather DigitalOcean Credentials

Now we need to create the credentials that GitLab Runner will use to create new Droplets using your DigitalOcean account.

Visit your DigitalOcean dashboard and click API. On the next screen, look for Personal access tokens and click Generate New Token.

Give the new token a name you will recognize such as GitLab Runner Access and ensure that both the read and write scopes are enabled, as we need the Droplet to create new machines without human intervention.

Copy the token somewhere safe as we’ll use it in the next step. You can’t retrieve this token again without regenerating it, so be sure it’s stored securely.

Step 8 — Edit GitLab Runner Configuration Files

To bring all of these components together, we need to finish configuring our bastion Droplet to communicate with your DigitalOcean account.

In your SSH connection to your bastion Droplet, use your favorite text editor, such as nano, to open the GitLab Runner configuration file for editing:

  1. nano /etc/gitlab-runner/config.toml

This configuration file is responsible for the rules your CI setup uses to scale up and down on demand. To configure the bastion to autoscale on demand, you need to add the following lines:

concurrent = 50   # All registered Runners can run up to 50 concurrent builds

  url = "https://example.digitalocean.com"
  token = "existinggitlabtoken"             # Note this is different from the registration token used by `gitlab-runner register`
  name = "example-runner"
  executor = "docker+machine"        # This Runner is using the 'docker+machine' executor
  limit = 10                         # This Runner can execute up to 10 builds (created machines)
    image = "alpine:latest"               # Our secure image
    IdleCount = 1                    # The amount of idle machines we require for CI if build queue is empty
    IdleTime = 600                   # Each machine can be idle for up to 600 seconds, then destroyed
    MachineName = "gitlab-runner-autoscale-%s"    # Each machine will have a unique name ('%s' is required and generates a random number)
    MachineDriver = "digitalocean"   # Docker Machine is using the 'digitalocean' driver
    MachineOptions = [
        "digitalocean-image=coreos-stable", # The DigitalOcean system image to use by default
        "digitalocean-ssh-user=core", # The default SSH user
        "digitalocean-access-token=DO_ACCESS_TOKEN", # Access token from Step 7
        "digitalocean-region=nyc3", # The data center to spawn runners in
        "digitalocean-size=1gb", # The size (and price category) of your spawned runners
        "digitalocean-private-networking" # Enable private networking on runners
    Type = "s3"   # The Runner is using a distributed cache with the S3-compatible Spaces service
    ServerAddress = "nyc3.spaces.digitaloceanspaces.com"
    AccessKey = "YOUR_SPACES_KEY"
    SecretKey = "YOUR_SPACES_SECRET"
    BucketName = "your_bucket_name"
    Insecure = true # We do not have a SSL certificate, as we are only running locally 

Once you’ve added the new lines, customize the access token, region and Droplet size based on your setup. For the purposes of this tutorial, we’ve used the smallest Droplet size of 1GB and created our Droplets in NYC3. Be sure to use the information that is relevant in your case.

You also need to customize the cache component, and enter your Space’s server address from the infrastructure configuration step, access key, secret key and the name of the Space that you created.

When completed, restart GitLab Runner to make sure the configuration is being used:

  1. gitlab-runner restart

If you would like to learn about more all available options, including off-peak hours, you can read GitLab’s advanced documentation.

Step 9 — Test Your GitLab Runner

At this point, our GitLab Runner bastion Droplet is configured and is able to create DigitalOcean Droplets on demand, as the CI queue fills up. We’ll need to test it to be sure it works by heading to your GitLab instance and the project we imported in Step 1.

To trigger a build, edit the readme.md file by clicking on it, then clicking edit, and add any relevant testing text to the file, then click Commit changes.

Now a build will be automatically triggered, which can be found under the project’s CI/CD option in the left navigation.

On this page you should see a pipeline entry with the status of running. In your DigitalOcean account, you’ll see a number of Droplets automatically created by GitLab Runner in order to build this change.

Congratulations! Your CI pipeline is cloud scalable and now manages its own resource usage. After the specified idle time, the machines should be automatically destroyed, but we recommend verifying this manually to ensure you aren’t unexpectedly billed.


In some cases, GitLab may report that the runner is unreachable and as a result perform no actions, including deploying new runners. You can troubleshoot this by stopping GitLab Runner, then starting it again in debug mode:

  1. gitlab-runner stop
  2. gitlab-runner --debug start

The output should throw an error, which will be helpful in determining which configuration is causing the issue.

If your configuration creates too many machines, and you wish to remove them all at the same time, you can run this command to destroy them all:

  1. docker-machine rm $(docker-machine ls -q)

For more troubleshooting steps and additional configuration options, you can refer to GitLab’s documentation.


You’ve successfully set up an automated CI/CD pipeline using GitLab Runner and Docker. From here, you could configure higher levels of caching with Docker Registry to optimize performance or explore the use of tagging code builds to specific GitLab code runners.

For more on GitLab Runner, see the detailed documentation, or to learn more, you can read GitLab’s series of blog posts on how to make the most of your continuous integration pipeline.

This post also appears on the GitLab Blog.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us

About the authors
Default avatar
Owen Williams


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

The coreos image doesn’t exist anymore. One has to create a custom image based on flatcar for example. See: https://www.flatcar.org/docs/latest/installing/cloud/digitalocean/

Once you created the image, get it’s numerical ID and use it in the runner config instead of coreos-stable like this:

MachineOptions = [
        "digitalocean-image=NUMERICAL_CUSTOM_IMAGE_ID", # The ID of your custom image
        "digitalocean-ssh-user=core", # The default SSH user
        "digitalocean-access-token=DO_ACCESS_TOKEN", # Access token from Step 7
        "digitalocean-region=nyc3", # The data center to spawn runners in
        "digitalocean-size=1gb", # The size (and price category) of your spawned runners
        "digitalocean-private-networking" # Enable private networking on runners

not working anymore as of 2021. Stop wasting time.

  1. the coreos-stable image has reached EOL
  2. the size parameter (1gb) is outdated
  3. Gitlab-runner just doesn’t play well together with docker-machine, and gitlab will not fix it

What Gitlab suggests us to do:

Use Kubernetes.

Can someone explain, what is 6 step for?

I faced a problem, that GitLab runner requires to install Docker-machine on temporary machine as well on a host. The only way seem to prepare my own image for this purpose

Nice tutorial!

I wanted to report a few minor issues I noticed:

  • in step 3 the fist command to install docker machine has a dangling && \ that shouldn’t be there
  • in step 5 the current version of gitlab-runner doesn’t ask anymore all the questions
  • in step 8 the current syntax of /etc/gitlab-runner/config.toml has slightly changed (according to the gitlab doc), for instance the cache settings are now different (see the doc )

Another strange thing I noticed by inspecting the logs on the bastion host is that it seems the communication between bastion and runners is not happening on the private network despite the setting that says the contrary. I may be wrong though, as I’m new to DO networking.

If your machines get stuck can kill them all with:

docker-machine ls -q | xargs docker-machine rm -f

Great article!

Everything works as expected here but the gitlab cache; I can not manage to make it work with Spaces

Are you sure this line is correct?

ServerAddress = "nyc3.spaces.digitaloceanspaces.com"

My pipelines says that URL doesn’t exist. I tried to change it to

ServerAddress = "nyc3.digitaloceanspaces.com"

but then I get authentication problems

I set everything up according to the instructions, but the test pipeline remains in pending status waiting for a runner to pick it up.

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel