Self Managed Runners

Runners are virtual machines that execute jobs in a GitLab CI/CD pipeline. They clone your repository, install dependencies, and run your build, test, and deploy commands. While GitLab.com offers hosted SAST runners out of the box, self-managed runners let you deploy and control your own infrastructure.

GitLab’s shared hosted runners spin up fresh VMs on Linux, Windows, macOS, or GPU-enabled instances with zero configuration.

Self-managed runners provide:

Fully customizable execution environments (OS, tools, libraries).
Dedicated capacity with no queue delays.
Horizontal scaling for parallel workflows.
Geographic placement for low latency and data residency.
Enforced security and compliance controls.

The image lists five benefits of self-managed runners: custom-execution environment, controlled environment for security, eliminate wait time, scalability, and reduced latency.

While GitLab-hosted runners are easy to start, self-managed runners give you full control over performance, security, and cost.

Runner Scopes

You can register self-managed runners at three levels:

Scope	Availability	Use Case	Registration Location
Shared runner	All groups and projects	General-purpose CI/CD workloads	Admin Area > CI/CD > Runners
Group runner	All projects in a specific group	Team-based resource sharing	Group Settings > CI/CD > Runners
Project runner	A single project	Project-specific pipelines	Project Settings > CI/CD > Runners

The image shows three icons representing "Shared," "Group," and "Project" under the title "Self-Managed Runners." Each icon is in a colored circle with a relevant symbol.

Project-Level Runner Setup

To register a runner for one project:

Navigate to Settings > CI/CD in your project.
Under Runners, optionally disable any existing shared runners.
Click Expand next to Set up a specific Runner manually, then select New project runner.

The image shows a user interface for setting up a new project runner, allowing the selection of operating systems (Linux, macOS, Windows) and containers (Docker, Kubernetes) for self-managed runners.

During setup you can:

Choose OS and architecture (Linux, Windows, macOS).
Add tags to route jobs (docker, linux, nodejs).
Enable Run untagged jobs for broader job assignment.
Configure protection, pausing, and other advanced options.

The image shows a configuration interface for self-managed runners, including sections for adding tags and optional configuration settings like pausing and protection.

Click Create runner to generate your registration token and get platform-specific installation steps.

Installing GitLab Runner

Install the GitLab Runner binary on your host before registering:

# 1. Download the Linux AMD64 binary
sudo curl -L "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64" \
  -o /usr/local/bin/gitlab-runner

# 2. Make it executable
sudo chmod +x /usr/local/bin/gitlab-runner

# 3. Create a dedicated service user
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

# 4. Install and start as a system service
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

Ensure /usr/local/bin/gitlab-runner has correct ownership and permissions to prevent privilege escalation.

Registering the Runner

Run the interactive registration command:

sudo gitlab-runner register \
  --url "https://gitlab.com/" \
  --registration-token "GLRT-xxxxxxxxxxxxxxxxxxxx"

You’ll be prompted for:

Runner name (e.g., ci-nodejs-linux).
Executor (shell, docker, kubernetes).
Additional settings: default Docker image, tags, locked/unlocked status.

Successful registration writes all details to /etc/gitlab-runner/config.toml.

Keep your registration token secret. Do not commit it to source control or share publicly.

Customizing `config.toml`

Open /etc/gitlab-runner/config.toml to tailor your runner:

name and tags for job routing.
executor block to configure Docker images, volumes, and networks.
Resource limits: cpu, memory, and disk quotas.
Environment variables ([[runners.environment]]).
Cache and artifact paths for faster CI/CD runs.

Using Tags in `.gitlab-ci.yml`

Target specific runners by matching tags:

workflow:
  name: Self-Managed Runner Tags

unit_tests:
  stage: test
  tags:
    - docker
    - nodejs
    - linux
  script:
    - npm install
    - npm test

Return to Settings > CI/CD in your project to monitor runner status, job history, and registered tags.

Introduction

Architecture & Core Concepts

Continuous Integration with GitLab

Continuous Deployment with GitLab

Optimization, Security and Monitoring