Gitlab Runner

Installing GitLab CI Runners: A Practical Guide

Emily Thompson
August 19, 2023

An Overview of GitLab CI Runners

Welcome to, where we provide high-performance managed GitLab runners that reduce pipeline duration and lower costs compared to self-hosted runners. Now, let's dive into how you can install your own GitLab CI runners.

What is a Runner?

GitLab CI Runners are the unsung heroes that execute the jobs defined in your CI/CD pipelines. Essentially, they are machines separate from the one running the GitLab web application, handling the tasks defined in your .gitlab-ci.yml file. When you click "Run Pipeline" in GitLab, these runners get to work.

Benefits of Managed Runners

Why bother installing your own runners when offers ready-to-use shared runners? Here are a few reasons:

  • Reduce pipeline execution time: Shared runners are used by all users. During peak times, the wait can be long.
  • Full control over configuration: With your own runners, you can customize everything, from the operating system to security policies.
  • Security and compliance: Need to meet strict security requirements? Self-hosted runners make it possible.

Why Install Your Own Runners?

Limitations of Shared Runners

Shared runners have their drawbacks:

  • Variable wait times: At peak times, wait times can increase, slowing down your pipelines.
  • Specific configuration needs: Shared runners can't be tailored to specific requirements.

Advantages of Self-Hosted Runners

With self-hosted runners, you gain:

  • Total control over configuration and security: Adjust every detail to your needs.
  • Cost and performance optimization: Use machines that are cost-effective.
  • Flexibility: Adapt runners to your specific requirements.

Types of GitLab Runners

Shared Runners

Shared runners are available to all users. They require no installation or configuration and are ready to use.

Group Runners and Project Runners

  • Group Runners: Available to all projects and subgroups within a group.
  • Project Runners: Specific to a particular project.

Preparing to Install a Runner

Prerequisites and Preliminary Steps

Before installing a runner, here are a few steps you need to take:

  • Access GitLab settings: Go to Settings > CI/CD > Runners.
  • Configure necessary information: Operating system, tags, description, etc.

Storing Tokens

The runner's token is crucial. Make sure to store it securely, as it won't be accessible after you leave the configuration page.

Methods for Installing and Configuring Runners

Installation with an Authentication Token

Since GitLab version 15.6, using authentication tokens is recommended for registering runners. Here's how to proceed:

  1. Create a new runner: Go to Settings > CI/CD > Runners > New Project Runner.
  2. Complete the required information: Operating system, tags, description.
  3. Store the token: Keep it secure.

Standard Docker Runner Installation

Here's how to install a standard runner that executes Docker containers:

  1. Configure a virtual machine: Use Terraform and Google Cloud to create a virtual machine.
  2. Startup and shutdown scripts:
    • Startup script: To initialize and register the runner.
    • Shutdown script: To unregister the runner when the machine stops.

Deploying Runners in the Cloud

Benefits of Ephemeral Instances

Ephemeral instances offer cost reductions of up to 91%. They are ideal for non-critical tasks that can be replayed if the instance is reclaimed by the cloud provider.

Deploying a Standard Runner

Use Terraform to deploy a standard runner on Google Cloud. The code is divided into two main modules:

  • gitlab_ci_autoscaler_runner
  • gitlab_ci_standard_runner

The main module for the virtual machine is configured as follows:

hclCopier le code

resource "google_compute_instance" "gitlab_runner" {
 project = var.project_id
 name         = local.gitlab_runner_name
 machine_type = var.virtual_machine_type
 zone         =

The associated scripts initialize and register the runner.

Deploying an Autoscaler Runner

Autoscaling Concept

The autoscaler runner doesn't just execute containers. It controls the creation of "agent" virtual machines that perform the GitLab CI jobs. Docker Machine is used to manage these agents.

Configuration and Registration

Here's how to register an autoscaler runner:

bashCopier le code

gitlab-runner register \
 --non-interactive \
 --name="${gitlab_runner_name}" \
 --url="https://${gitlab_server_url}/" \
 --token="$${gitlab_runner_token}" \
 --executor="docker+machine" \
 --limit=20 \
 --docker-image="scratch:latest" \
 --docker-privileged=false \
 --docker-disable-cache=true \
 --machine-machine-driver=google \
 --machine-machine-name="${gitlab_runner_name_suffix}-%s" \
 --machine-idle-count-min=0 \
 --machine-idle-time=400 \
 --machine-max-builds=100 \
 --machine-machine-options=google-project=${gitlab_runner_google_project} \
 --machine-machine-options=google-network=${gitlab_runner_google_network} \
 --machine-machine-options=google-subnetwork=${gitlab_runner_google_subnetwork} \
 --machine-machine-options=google-machine-type=n1-standard-1 \
 --machine-machine-options=google-service-account=${gitlab_runner_google_service_account} \
 --machine-machine-options=google-scopes= \
 --machine-machine-options=google-zone=${gitlab_runner_google_zone} \
 --machine-machine-options=google-use-internal-ip=true \
 --machine-machine-options=google-use-internal-ip-only=true \
 --machine-machine-options=google-tags=gitlab-runner \
 --machine-machine-options=google-username=cosadmin \
 --machine-machine-options=google-metadata=enable-oslogin=FALSE \
 --machine-machine-options=google-machine-image=cos-cloud/global/images/cos-stable-105-17412-156-23 \

With the executor="docker+machine" parameter, Docker Machine manages the Docker agents on new virtual machines created as needed.

Optimizations and Improvements

Creating Ready-to-Use Images

To save time, create images with all necessary binaries (Docker, Docker Machine, GitLab Runner) using Packer and Ansible.

Implementing a Shared Cache

To avoid redownloading dependencies with each run, set up a shared cache. Use Google Cloud Storage and the virtual machine's service account to access the cache without storing a JSON key.


There you have it! You are now ready to install and configure your own GitLab CI runners. With self-hosted runners, you gain full control, optimize costs, and improve your pipeline performance. I hope this series of articles has helped you better understand and master GitLab CI.

For more details on how our high-performance managed GitLab runners can save you time and money, check out our product. Happy deploying!

Untitled UI logotext
© 2024 Cloud-Runner. All rights reserved.