DEV Community

giveitatry
giveitatry

Posted on

GitLab Runner Installation and Configuration Guide

This guide walks through the complete installation of a GitLab Runner on a Linux system using Docker, including additional configuration for environments behind a VPN and SSL setup for GitLab.

Prerequisites

  • Docker must be installed on the target machine.
  • You need root (sudo) access.
  • If operating behind a VPN, you must trust the custom CA used to sign the GitLab server's certificate.

Step-by-Step: Installing GitLab Runner

1. [VPN Only] Trust GitLab Server Certificate Authority (CA)

This step is required if your GitLab instance uses a private certificate.

a. Add CA Certificate

  1. Place your CA certificate (e.g., file.crt) in a new folder under trusted certificates: 
cd /usr/share/ca-certificates
sudo mkdir -p company-name
cd company-name
sudo cp /path/to/file.crt .
Enter fullscreen mode Exit fullscreen mode
  1. Edit the list of trusted certificates: 
sudo nano /etc/ca-certificates.conf
Enter fullscreen mode Exit fullscreen mode

Add the line:

company-name/file.crt
Enter fullscreen mode Exit fullscreen mode
  1. Update the system CA store: 
sudo update-ca-certificates
Enter fullscreen mode Exit fullscreen mode

2. Download GitLab Runner Binary 

sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
Enter fullscreen mode Exit fullscreen mode

3. Make It Executable 

sudo chmod +x /usr/local/bin/gitlab-runner
Enter fullscreen mode Exit fullscreen mode

4. Install as a System Service 

# Create GitLab Runner user
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

# Add to Docker group
sudo usermod -aG docker gitlab-runner

# Install and start runner service
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start
Enter fullscreen mode Exit fullscreen mode

5. Verify Installation 

gitlab-runner --version
sudo systemctl status gitlab-runner
Enter fullscreen mode Exit fullscreen mode

Registering the GitLab Runner

  1. Login to GitLab as Admin → Go to Admin Area > CI/CD > Runners.
  2. Click "Register a runner" and copy the registration token.
  3. On the runner server, run: 
sudo gitlab-runner register
Enter fullscreen mode Exit fullscreen mode

Follow prompts:

  • URL: https://example.com
  • Token: (Paste the token from GitLab)
  • Description: (e.g., docker-runner)
  • Tags: (Optional)
  • Executor: Choose docker for isolated environments.

Enabling SSL for GitLab (Optional)

If securing your GitLab instance with SSL:

1. Place Certificate and Key 

sudo mkdir -p /etc/gitlab/ssl
sudo cp yourdomain.crt yourdomain.key /etc/gitlab/ssl/
sudo chown root:root /etc/gitlab/ssl/*
sudo chmod 600 /etc/gitlab/ssl/*
Enter fullscreen mode Exit fullscreen mode

2. Edit GitLab Configuration

Edit /etc/gitlab/gitlab.rb:

external_url 'https://your.domain.com'

nginx['redirect_http_to_https'] = true
nginx['ssl_certificate'] = "/etc/gitlab/ssl/yourdomain.crt"
nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/yourdomain.key"
Enter fullscreen mode Exit fullscreen mode

3. Reconfigure GitLab 

sudo gitlab-ctl reconfigure
Enter fullscreen mode Exit fullscreen mode

Final Check

  • GitLab Runner status: sudo systemctl status gitlab-runner
  • GitLab accessible via https://your.domain.com
  • CI jobs trigger correctly with Docker executor

Notes

  • You can install multiple runners on different machines for load balancing.
  • Use GitLab tags to direct jobs to specific runners.
  • Ensure the runner has access to Docker images used in your CI pipelines.

Top comments (0)