How to set up GitLab Runner on DigitalOcean

Apr 19, 2016 · 6 min read
Achilleas Pipinellis GitLab profile


GitLab has built-in continuous integration to allow you to run a number of tasks as you prepare to deploy your software. Typical tasks might be to build a software package or to run tests as specified in a YAML file. These tasks need to run by something, and in GitLab this something is called a Runner; an application that processes builds.

In March we introduced GitLab Runner 1.1 with the cool feature of autoscaling and a week later we announced that all shared Runners on use autoscaling. The shared Runners can be used for free by any user with a account.

In this tutorial we will explore how easy it is to install and set up your own Runner on DigitalOcean; a Runner that will be 'specific' to your projects as we say in the GitLab lingo.


We will use the Docker executor since it has the most supported features according to the GitLab Runner executor compatibility chart. For this, we will need to install Docker on the server that will host the GitLab Runner.

Fortunately, DigitalOcean has a one-click image with Docker pre-installed on Ubuntu 14.04 and this is what we will use.

Note: You are free to use any Linux distribution supported by DigitalOcean, even FreeBSD. GitLab Runner is supported on all Operating Systems.

Create a droplet

Login to DigitalOcean and from the Control Panel, click on the "Create Droplet" button that is visible from any page.

Create Droplet

Under the "Choose an image" section, select the "One-click Apps" tab and click the "Docker" image (the version might differ).

Droplet app

The next step is to choose the droplet size and the region you would like to use. You are advised to use the 1 GB / 1 CPU droplet for quicker builds.


Add any SSH Keys, select any settings you'd like to use, and click "Create" at the bottom.

Finalize creation

Your Docker droplet will be created and available in a few minutes!

Install the GitLab Runner

First, login to the new droplet via SSH and verify that Docker is installed with:

docker info

This should show a bunch of information about the Docker version, the number of images and containers, etc. With that set, we're ready to install GitLab Runner.

GitLab provides a repository where you can easily install and update GitLab Runner. The supported distros as Debian, Ubuntu and CentOS. Let's install the repository with this one-line:

curl -L | sudo bash

Feel free to read the script before you execute it if you want.

Now let's install GitLab Runner:

sudo apt-get install gitlab-runner

And verify it's installed:

gitlab-runner --version

Excellent! We're now ready to start using it.

Note: For other installation methods and Operating Systems, see the installation documentation.

Register the GitLab Runner

Registering a Runner is the process of tying it with a specific GitLab project. Each project on GitLab has a unique token that is used by the Runner in order to be able to talk to GitLab via its API.

When we installed GitLab Runner in the previous step, we installed GitLab Runner the service. Each GitLab Runner service can spawn as many Runner processes you want, so you can eventually register multiple Runners in a single droplet, each of which can be tied to a separate project.

To register a Runner we first need to know the project's token. Go to your newly created project or pick one that already uses's shared Runners. Navigate to the project's Settings > Runners and notice that the shared Runners are enabled. In the left side you get detailed information on the steps needed to register a new Runner.

Runners settings

Now, let's get back to the droplet and start registering a Runner:

sudo gitlab-runner register

The command above is interactive, so you will be asked the information needed to register a new Runner.

Once answered all questions, you can verify that the Runner is registered with:

sudo gitlab-runner list

Now if you head back in your project's Settings > Runners you will see that the Runner appeared in the list.


You can now start using this specific Runner for your project and you may disable the shared Runners.

When you register a Runner via the gitlab-runner register command, the answers you give get written in the Runner's configuration file, which is located at /etc/gitlab-runner/config.toml. If we open this file after we registered the above Runner, here's what we see:

concurrent = 1

  name = "docker-1gb-ams2-01"
  url = ""
  token = "467f75b3123e08417b1df75b3e9b3d"
  executor = "docker"
    tls_verify = false
    image = "ruby:2.1"
    privileged = false
    disable_cache = false
    volumes = ["/cache"]
    Insecure = false

You can read all about config.toml in the official documentation.

Update the GitLab Runner

Updating the GitLab Runner is as easy as updating your Ubuntu system:

sudo apt-get update
sudo apt-get install gitlab-runner


In this brief tutorial we explored how to install and set up our own GitLab Runner on DigitalOcean. Following the steps from top to bottom shouldn't take more than 10 minutes. If you stumble upon any issues while your project builds, make sure to read the troubleshooting FAQs.

For a more detailed tutorial on GitLab Runner and CI, be sure to check a previous tutorial on Setting up GitLab Runner For Continuous Integration which provides a detailed real world example.

If you are new to GitLab CI, you can follow our Quick start guide to get you started.

Powered by DigitalOcean

Edit this page View source