gitlab-runner

Register a runner

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

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

$ sudo gitlab-runner unregister --name [name]

$ sudo gitlab-runner status

$ sudo gitlab-runner restart

$ sudo gitlab-runner verify

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

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.

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.

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.

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.

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.

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.

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