Skip to main content
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:
ScopeAvailabilityUse CaseRegistration Location
Shared runnerAll groups and projectsGeneral-purpose CI/CD workloadsAdmin Area > CI/CD > Runners
Group runnerAll projects in a specific groupTeam-based resource sharingGroup Settings > CI/CD > Runners
Project runnerA single projectProject-specific pipelinesProject 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:
  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.
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.

Watch Video