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.

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.

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:

Project-Level Runner Setup

To register a runner for one project:

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

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.

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

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.

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.

Links and References

• GitLab SAST Runners
• GitLab Runner Documentation
• GitLab CI/CD Basics