gitlab-runner
Execute GitLab CI/CD pipeline jobs
TLDR
Register a runner
Register a runner with a Docker executor
Unregister a runner
Display the status of the runner service
Restart the runner service
Check if the registered runners can connect to GitLab
SYNOPSIS
gitlab-runner
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.