LinuxCommandLibrary

gitlab-runner

Execute GitLab CI/CD pipeline jobs

TLDR

Register a runner

$ sudo gitlab-runner register --url [https://gitlab.example.com] --registration-token [token] --name [name]
copy

Register a runner with a Docker executor
$ sudo gitlab-runner register --url [https://gitlab.example.com] --registration-token [token] --name [name] --executor [docker]
copy

Unregister a runner
$ sudo gitlab-runner unregister --name [name]
copy

Display the status of the runner service
$ sudo gitlab-runner status
copy

Restart the runner service
$ sudo gitlab-runner restart
copy

Check if the registered runners can connect to GitLab
$ sudo gitlab-runner verify
copy

SYNOPSIS

gitlab-runner [command options] [arguments...]

PARAMETERS

register
    Registers a new runner with a GitLab instance.

run
    Starts the runner process to pick up and execute jobs.

exec
    Executes a CI job locally, useful for debugging and testing.

list
    Lists all configured GitLab Runners.

verify
    Checks the status of registered runners and removes invalid ones.

unregister
    Unregisters a runner from GitLab and removes its configuration.

install
    Installs the runner as a system service (e.g., systemd on Linux).

start
    Starts the runner system service.

stop
    Stops the runner system service.

status
    Shows the status of the runner system service.

--version
    Displays the GitLab Runner version information.

help
    Shows help for a command or global options.

DESCRIPTION

gitlab-runner is the open-source application that executes jobs in a GitLab CI/CD pipeline.
It can be installed on various operating systems and configured to connect to a GitLab instance. Runners pick up jobs from GitLab, execute them based on the .gitlab-ci.yml configuration, and send the results (logs, artifacts) back to GitLab.
Runners can be configured with different executors, such as Docker, Kubernetes, Shell, SSH, Parallels, VirtualBox, or custom executors, allowing flexibility in how jobs are run and providing isolation.
It acts as the backbone for automating software development workflows, enabling continuous integration, continuous delivery, and continuous deployment directly within the GitLab platform.

CAVEATS

gitlab-runner requires a GitLab instance (SaaS or self-managed) to function and receive jobs.
Proper configuration of executors (e.g., Docker, Kubernetes) is crucial for security, isolation, and performance.
Resource management (CPU, memory, disk) is vital, especially for shared runners executing multiple jobs concurrently.
Network connectivity between the runner machine and the GitLab instance, as well as any external services required by jobs, must be ensured.

CONFIGURATION FILE

The primary configuration for gitlab-runner is managed through a config.toml file, typically located at /etc/gitlab-runner/config.toml on Linux.
This file defines registered runners, their executors, concurrent job limits, and other operational settings crucial for runner behavior.

EXECUTORS

gitlab-runner supports various executors that determine how jobs are run:
Docker: Runs jobs inside Docker containers (most common, provides good isolation).
Shell: Runs jobs directly on the runner machine's shell environment (simple, but less isolated).
Kubernetes: Runs jobs as pods within a Kubernetes cluster (scalable, cloud-native).
Other executors include SSH, Parallels, VirtualBox, and custom solutions, each offering different levels of isolation, performance, and setup complexity.

HISTORY

gitlab-runner evolved alongside GitLab CI/CD, which was initially a separate project (GitLab CI) before being fully integrated into GitLab. As GitLab matured into a complete DevOps platform, gitlab-runner became its dedicated and highly configurable job execution agent, supporting various environments and scales.
Its development consistently focuses on flexibility, security, and performance for CI/CD workloads, adapting to modern containerization and orchestration technologies to meet the demands of continuous delivery.

SEE ALSO

git(1), docker(1), systemctl(1), kubectl(1)

Copied to clipboard