GitLab Runner

https://docs.gitlab.com/runner/
Admin
A robust application that runs jobs in a GitLab CI/CD pipeline, handling everything from script...
Tokens:489,392
Snippets:3,469
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run Xcode first launch setup

Source: https://docs.gitlab.com/runner/configuration/macos_setup/index.md

Agree to the license and install recommended Xcode components via the command line.

```shell
sudo xcodebuild -runFirstLaunch
```

--------------------------------

### Install and start GitLab Runner service on macOS

Source: https://docs.gitlab.com/runner/install/osx/index.md

Creates a LaunchAgent plist at ~/Library/LaunchAgents/gitlab-runner.plist and starts the user-mode runner service. Execute in a local GUI terminal as the target user account.

```shell
cd ~
gitlab-runner install
gitlab-runner start
```

--------------------------------

### Install and start GitLab Runner as a service

Source: https://docs.gitlab.com/runner/install/linux-manually

Installs GitLab Runner as a service running as the 'gitlab-runner' user with a working directory of /home/gitlab-runner, then starts the service. Ensure /usr/local/bin is in $PATH for root to avoid 'command not found' errors.

```shell
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start
```

--------------------------------

### Install Go on macOS using installation package (.pkg)

Source: https://docs.gitlab.com/runner/development/index.md

Downloads and launches the macOS Go installer package (.pkg), configures PATH, and installs yq.

```shell
wget https://storage.googleapis.com/golang/go1.26.5.darwin-amd64.pkg
open go*-*.pkg
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Install and start GitLab Runner service

Source: https://docs.gitlab.com/runner/install/osx

Installs and starts the GitLab Runner service as a LaunchAgent in the user's home directory.

```shell
cd ~
gitlab-runner install
gitlab-runner start
```

--------------------------------

### Install and start GitLab Runner and rbenv

Source: https://docs.gitlab.com/runner/configuration/macos_setup/index.md

Install rbenv and GitLab Runner using Homebrew and start the GitLab Runner service.

```shell
brew install rbenv gitlab-runner
brew services start gitlab-runner
```

--------------------------------

### Install dependencies and Go on Debian or Ubuntu

Source: https://docs.gitlab.com/runner/development/index.md

Installs build tools, downloads and unpacks the Go runtime to /usr/local, updates PATH, and installs the yq binary on Debian/Ubuntu systems.

```shell
sudo apt-get install -y mercurial git-core wget make build-essential
wget https://storage.googleapis.com/golang/go1.26.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Agree to Xcode license and install components

Source: https://docs.gitlab.com/runner/configuration/macos_setup

Agrees to the Xcode license and installs recommended components. Run after installing Xcode.

```shell
sudo xcodebuild -runFirstLaunch

```

--------------------------------

### Run the setup script (chmod and sudo)

Source: https://docs.gitlab.com/runner/configuration/slot_based_cgroups

Makes the setup script executable and runs it with sudo to create the systemd slices.

```shell
chmod +x gitlab-runner-systemd-slice-setup.sh
sudo ./gitlab-runner-systemd-slice-setup.sh
```

--------------------------------

### Install and start GitLab Runner service using Built-in System Account

Source: https://docs.gitlab.com/runner/install/windows/index.md

Installs GitLab Runner as a Windows service using the default Built-in System Account and starts it. Run these commands from an elevated command prompt in the runner installation directory.

```powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe install
.\gitlab-runner.exe start
```

--------------------------------

### Install and start GitLab Runner service using user account

Source: https://docs.gitlab.com/runner/install/windows/index.md

Installs and starts GitLab Runner as a Windows service under a specific user account. Requires supplying a valid username and password for Windows service authentication.

```powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
.\gitlab-runner.exe start
```

--------------------------------

### Install Go on macOS using binary package

Source: https://docs.gitlab.com/runner/development/index.md

Downloads and unpacks the Go darwin tarball into /usr/local, sets the environment PATH, and downloads yq on macOS.

```shell
wget https://storage.googleapis.com/golang/go1.26.5.darwin-amd64.tar.gz
sudo tar -C /usr/local -xzf go*-*.tar.gz
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Example runner configuration

Source: https://docs.gitlab.com/runner/configuration/advanced-configuration

Example runner configuration showing common fields such as name, url, token, limit, executor, builds_dir, shell, environment, and clone_url.

```toml
[[runners]]
  name = "example-runner"
  url = "http://gitlab.example.com/"
  token = "TOKEN"
  limit = 0
  executor = "docker"
  builds_dir = ""
  shell = ""
  environment = ["ENV=value", "LC_ALL=en_US.UTF-8"]
  clone_url = "http://gitlab.example.local"
```

--------------------------------

### Start GitLab Runner directly

Source: https://docs.gitlab.com/runner/install/z-os/index.md

Start the GitLab Runner service directly from the command line after navigating to the installation bin directory.

```shell
gitlab-runner start
```

--------------------------------

### Configuration template file example

Source: https://docs.gitlab.com/runner/register

Create a configuration template file in .toml format with your specifications. The template supports only a single [[runners]] section and does not support global options.

```toml
[[runners]]
  [runners.kubernetes]
  [runners.kubernetes.volumes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty_dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"
```

--------------------------------

### Unmet dependencies error when installing specific version without helper images

Source: https://docs.gitlab.com/runner/install/linux-repository/index.md

Example of the unmet dependencies error produced by apt when gitlab-runner-helper-images is omitted during a version-specific installation.

```shell
sudo apt install gitlab-runner=17.7.1-1
...
The following packages have unmet dependencies:
 gitlab-runner : Depends: gitlab-runner-helper-images (= 17.7.1-1) but 17.8.3-1 is to be installed
E: Unable to correct problems, you have held broken packages.
```

--------------------------------

### Install Go and yq on FreeBSD

Source: https://docs.gitlab.com/runner/development

Installs Go and yq on FreeBSD using pkg. Use this to set up the Go runtime and required tools for GitLab Runner development.

```shell
pkg install go-1.26.5 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Configure `[runners.docker.services]` with full runner config

Source: https://docs.gitlab.com/runner/configuration/advanced-configuration/index.md

Complete example of the `[runners.docker]` section with service definitions, ulimits, and sysctls. Shows how to configure `[[runners.docker.services]]` entries with `name`, `alias`, `entrypoint`, `command`, and `environment` parameters.

```toml
[runners.docker]
  host = ""
  hostname = ""
  tls_cert_path = "/Users/ayufan/.boot2docker/certs"
  image = "ruby:3.3"
  memory = "128m"
  memory_swap = "256m"
  memory_reservation = "64m"
  oom_kill_disable = false
  cpuset_cpus = "0,1"
  cpuset_mems = "0,1"
  cpus = "2"
  dns = ["8.8.8.8"]
  dns_search = [""]
  service_memory = "128m"
  service_memory_swap = "256m"
  service_memory_reservation = "64m"
  service_cpuset_cpus = "0,1"
  service_cpus = "2"
  services_limit = 5
  privileged = false
  group_add = ["docker"]
  cap_add = ["NET_ADMIN"]
  cap_drop = ["DAC_OVERRIDE"]
  devices = ["/dev/net/tun"]
  disable_cache = false
  wait_for_services_timeout = 30
  cache_dir = ""
  volumes = ["/data", "/home/project/cache"]
  extra_hosts = ["other-host:127.0.0.1"]
  shm_size = 300000
  volumes_from = ["storage_container:ro"]
  links = ["mysql_container:mysql"]
  allowed_images = ["ruby:*", "python:*", "php:*"]
  allowed_services = ["postgres:9", "redis:*", "mysql:*"]
  log_options = { env = "GITLAB_CI_JOB_ID,GITLAB_CI_JOB_NAME", labels = "com.gitlab.gitlab-runner.type" }
  [runners.docker.ulimit]
    "rtprio" = "99"
  [[runners.docker.services]]
    name = "registry.example.com/svc1"
    alias = "svc1"
    entrypoint = ["entrypoint.sh"]
    command = ["executable","param1","param2"]
    environment = ["ENV1=value1", "ENV2=value2"]
  [[runners.docker.services]]
    name = "redis:2.8"
    alias = "cache"
  [[runners.docker.services]]
    name = "postgres:9"
    alias = "postgres-db"
  [runners.docker.sysctls]
    "net.ipv4.ip_forward" = "1"
```

--------------------------------

### Install and start GitLab Runner service logon failure error

Source: https://docs.gitlab.com/runner/install/windows/index.md

Shows the logon failure error occurring during service installation and startup when the user lacks SeServiceLogonRight permissions. Grant the Log on as a service right in Local Security Policy to fix the failure.

```shell
gitlab-runner install --password WINDOWS_MACHINE_PASSWORD
gitlab-runner start
FATA[0000] Failed to start GitLab Runner: The service did not start due to a logon failure.
```

--------------------------------

### Setup cgroupfs driver cgroup v2 hierarchy (alternative script and run)

Source: https://docs.gitlab.com/runner/configuration/slot_based_cgroups

Setup script for cgroupfs driver (alternative). Creates cgroup v2 hierarchy for GitLab Runner slot-based cgroups, configuring 4 slots on an 8-core machine with each slot pinned to 2 CPUs. Must be run as root; requires cgroup v2 and Docker using the cgroupfs driver. The script creates raw cgroup directories and enables memory, cpu, and cpuset controllers. The second command makes the script executable and runs it with sudo.

```shell
#!/bin/bash
# gitlab-runner-cgroup-setup.sh
# Script to set up cgroup v2 hierarchy for GitLab Runner slot-based cgroups
# This example configures 4 slots on an 8-core machine, with each slot pinned to 2 CPUs
# Use this script only if Docker is using the cgroupfs driver (not systemd)

set -e

CGROUP_ROOT="/sys/fs/cgroup"
RUNNER_CGROUP="gitlab-runner"
MAX_SLOTS=4  # Adjust based on your capacity_per_instance configuration

# CPU pinning configuration (2 CPUs per slot on an 8-core machine)
# Format: "cpu_list" - adjust based on your CPU topology
declare -a CPU_ASSIGNMENTS=(
    "0-1"    # Slot 0: CPUs 0 and 1
    "2-3"    # Slot 1: CPUs 2 and 3
    "4-5"    # Slot 2: CPUs 4 and 5
    "6-7"    # Slot 3: CPUs 6 and 7
)

# Check if running as root
if [[ $EUID -ne 0 ]]; then
   echo "This script must be run as root for cgroup setup"
   exit 1
fi

# Verify cgroup v2 is available
if [[ ! -f "$CGROUP_ROOT/cgroup.controllers" ]]; then
    echo "Error: cgroup v2 not detected. This script requires cgroup v2."
    exit 1
fi

echo "Setting up cgroup v2 hierarchy for GitLab Runner"
echo "Configuration: $MAX_SLOTS slots on an 8-core machine (2 CPUs per slot)"

# Create base runner cgroup
mkdir -p "$CGROUP_ROOT/$RUNNER_CGROUP"

# Enable controllers if available
if [[ -f "$CGROUP_ROOT/cgroup.controllers" ]]; then
    echo "+memory +cpu +cpuset" > "$CGROUP_ROOT/cgroup.subtree_control" 2>/dev/null || true
fi

# Create slot-specific cgroups
for ((slot=0; slot<MAX_SLOTS; slot++)); do
    slot_path="$CGROUP_ROOT/$RUNNER_CGROUP/slot-$slot"
    echo "Creating cgroup for slot $slot (CPUs: ${CPU_ASSIGNMENTS[$slot]})"

    mkdir -p "$slot_path"

    # Enable controllers for this slot
    if [[ -f "$CGROUP_ROOT/$RUNNER_CGROUP/cgroup.controllers" ]]; then
        echo "+memory +cpu +cpuset" > "$CGROUP_ROOT/$RUNNER_CGROUP/cgroup.subtree_control" 2>/dev/null || true
    fi

    # Pin slot to specific CPUs
    echo "${CPU_ASSIGNMENTS[$slot]}" > "$slot_path/cpuset.cpus"

    # Set memory nodes (usually 0 for single NUMA node systems)
    echo "0" > "$slot_path/cpuset.mems"

    # Set permissions for GitLab Runner user
    chown -R gitlab-runner:gitlab-runner "$slot_path" 2>/dev/null || true
done

echo "Cgroup setup complete!"

# Verify setup
echo ""
echo "Verifying cgroup setup:"
for ((slot=0; slot<MAX_SLOTS; slot++)); do
    slot_path="$CGROUP_ROOT/$RUNNER_CGROUP/slot-$slot"
    cpus=$(cat "$slot_path/cpuset.cpus")
    echo "  Slot $slot: CPUs $cpus"
done
```

```shell
chmod +x gitlab-runner-cgroup-setup.sh
sudo ./gitlab-runner-cgroup-setup.sh
```

--------------------------------

### LXD prepare.sh: destroy, launch, and install dependencies

Source: https://docs.gitlab.com/runner/executors/custom_examples/lxd

The prepare script for the LXD custom executor. It destroys any existing container with the same name, launches a new Ubuntu 22.04 container, waits for it to start, and installs Git LFS and the gitlab-runner binary. It sources base.sh for variables and uses SYSTEM_FAILURE_EXIT_CODE to signal retryable system failures.

```bash
#!/usr/bin/env bash

# /opt/lxd-driver/prepare.sh

currentDir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
source ${currentDir}/base.sh # Get variables from base.

set -eo pipefail

# trap any error, and mark it as a system failure.
trap "exit $SYSTEM_FAILURE_EXIT_CODE" ERR

start_container () {
    if lxc info "$CONTAINER_ID" >/dev/null 2>/dev/null ; then
        echo 'Found old container, deleting'
        lxc delete -f "$CONTAINER_ID"
    fi

    # The container image is hardcoded, but you can use
    # the `CI_JOB_IMAGE` predefined variable
    # https://docs.gitlab.com/ci/variables/predefined_variables/
    # which is available under `CUSTOM_ENV_CI_JOB_IMAGE` to allow the
    # user to specify the image. The rest of the script assumes that
    # you are running on an ubuntu image so modifications might be
    # required.
    lxc launch ubuntu:22.04 "$CONTAINER_ID"

    # Wait for container to start, we are using systemd to check this,
    # for the sake of brevity.
    for i in $(seq 1 10); do
        if lxc exec "$CONTAINER_ID" -- sh -c "systemctl isolate multi-user.target" >/dev/null 2>/dev/null; then
            break
        fi

        if [ "$i" == "10" ]; then
            echo 'Waited for 10 seconds to start container, exiting..'
            # Inform GitLab Runner that this is a system failure, so it
            # should be retried.
            exit "$SYSTEM_FAILURE_EXIT_CODE"
        fi

        sleep 1s
    done
}

install_dependencies () {
    # Install Git LFS, git comes pre installed with ubuntu image.
    lxc exec "$CONTAINER_ID" -- sh -c 'curl -s "https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh" | sudo bash'
    lxc exec "$CONTAINER_ID" -- sh -c "apt-get install -y git-lfs"

    # Install gitlab-runner binary since we need for cache/artifacts.
    lxc exec "$CONTAINER_ID" -- sh -c 'curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"'
    lxc exec "$CONTAINER_ID" -- sh -c "chmod +x /usr/local/bin/gitlab-runner"
}

echo "Running in $CONTAINER_ID"

start_container

install_dependencies
```

--------------------------------

### config.toml with check_interval and multiple runners

Source: https://docs.gitlab.com/runner/configuration/advanced-configuration

Example config.toml showing check_interval = 10 with two runner sections. With two runners, the sleep interval is 5 seconds, so each runner gets a request every 10 seconds.

```toml
# Example `config.toml` file

concurrent = 100 # A global setting for job concurrency that applies to all runner sections defined in this `config.toml` file.
log_level = "warning"
log_format = "json"
check_interval = 10 # Value in seconds

[[runners]]
  name = "runner-1"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "shell"
  (...)

[[runners]]
  name = "runner-2"
  url = "Your Gitlab instance URL (for example, `https://gitlab.com`)"
  executor = "docker"
  (...)
```

--------------------------------

### Set up MinIO cache server

Source: https://docs.gitlab.com/runner/configuration/speed_up_job_execution/index.md

Commands to set up a MinIO cache server: start the MinIO container, get the server IP, and create a bucket directory. The port 9005 can be modified. The bucket name is 'runner' by default; all caches are stored in /export.

```shell
docker run -d --restart always -p 9005:9000 \
        -v /.minio:/root/.minio -v /export:/export \
        -e "MINIO_ROOT_USER=<minio_root_username>" \
        -e "MINIO_ROOT_PASSWORD=<minio_root_password>" \
        --name minio \
        minio/minio:latest server /export
```

```shell
hostname --ip-address
```

```shell
sudo mkdir /export/runner
```

--------------------------------

### Install dependencies and Go on FreeBSD

Source: https://docs.gitlab.com/runner/development/index.md

Uses FreeBSD pkg to install Go, gmake, git, and mercurial, then configures PATH and downloads yq.

```shell
pkg install go-1.26.5 gmake git mercurial
export PATH="$(go env GOBIN):$PATH"
YQ_BINARY="yq_$(go env GOHOSTOS)_$(go env GOHOSTARCH).tar.gz"
wget https://github.com/mikefarah/yq/releases/download/latest/${YQ_BINARY}.tar.gz
sudo tar -C /usr/local -xzf ${YQ_BINARY}.tar.gz
```

--------------------------------

### Run GitLab Runner Docker container with SELinux volume flag

Source: https://docs.gitlab.com/runner/install/docker/index.md

Start the GitLab Runner container configured with the `:Z` volume flag for SELinux. If running SELinux in enforcing mode, install `selinux-dockersock` to avoid `Permission denied` errors accessing `/var/run/docker.sock`.

```shell
docker run -d --name gitlab-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
  gitlab/gitlab-runner:latest
```

--------------------------------

### Install GitLab Runner and create directories

Source: https://docs.gitlab.com/runner/configuration/runner_autoscale_aws_fargate/index.md

Creates required directories for runner metadata, builds, and cache, then downloads and installs GitLab Runner from the official repository.

```shell
sudo mkdir -p /opt/gitlab-runner/{metadata,builds,cache}
curl -s "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
sudo apt install gitlab-runner
```

--------------------------------

### Uninstall GitLab Runner Operator on Kubernetes

Source: https://docs.gitlab.com/runner/install/operator

These commands uninstall the GitLab Runner Operator on Kubernetes. They delete the Runner CRD, the secret, the Operator subscription, and the ClusterServiceVersion (CSV). The output of the get command shows the installed CSV version, which is used in the subsequent delete command.

```shell
kubectl delete -f gitlab-runner.yml
```

```shell
kubectl delete -f gitlab-runner-secret.yml
```

```shell
kubectl delete subscription my-gitlab-runner-operator -n operators
```

```shell
kubectl get clusterserviceversion -n operators
NAME                            DISPLAY         VERSION   REPLACES   PHASE
gitlab-runner-operator.v1.7.0   GitLab Runner   1.7.0                Succeeded
```

```shell
kubectl delete clusterserviceversion gitlab-runner-operator.v1.7.0 -n operators
```

--------------------------------

### Configure container lifecycle hooks in config.toml

Source: https://docs.gitlab.com/runner/executors/kubernetes

Configure container lifecycle hooks in the GitLab Runner config.toml. The example sets a PostStart exec hook that touches a file and a PreStop HTTP GET hook with custom headers. Each hook type allows only one handler.

```toml
[[runners]]
  name = "kubernetes"
  url = "https://gitlab.example.com/"
  executor = "kubernetes"
  token = "yrnZW46BrtBFqM7xDzE7dddd"
  [runners.kubernetes]
    image = "alpine:3.11"
    privileged = true
    namespace = "default"
    [runners.kubernetes.container_lifecycle.post_start.exec]
      command = ["touch", "/builds/postStart.txt"]
    [runners.kubernetes.container_lifecycle.pre_stop.http_get]
      port = 8080
      host = "localhost"
      path = "/test"
      [[runners.kubernetes.container_lifecycle.pre_stop.http_get.http_headers]]
        name = "header_name_1"
        value = "header_value_1"
      [[runners.kubernetes.container_lifecycle.pre_stop.http_get.http_headers]]
        name = "header_name_2"
        value = "header_value_2"
```
Tokens:
Raw