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 [global-options] <command> [command-options] [arguments]

--builds-dir string
    Directory for builds (default: /home/gitlab-runner/builds)

--config-file string
    Custom config file path (default: /etc/gitlab-runner/config.toml)

-D, --debug
    Enable debug output

-h, --help
    Show help

--log-file string
    Log file path (default: stdout/stderr)

--log-format string
    Log format: text, json (default: text)

--log-level string
    Log level: panic, fatal, error, warn, info, debug (default: info)

--service string
    Service name (uses defaults if empty)

--user string
    User to run as (uses default if empty)

--version
    Show version info

--working-directory string
    Base directory for builds (default: /home/gitlab-runner)

gitlab-runner is the command-line interface for managing GitLab Runners, lightweight agents that execute CI/CD jobs from GitLab pipelines. Runners poll the GitLab server for pending jobs defined in .gitlab-ci.yml files, execute them using specified executors (e.g., shell, Docker, Kubernetes, Parallels, SSH, virtualbox, custom), and report results back.

Key use cases include self-hosted infrastructure for faster, secure, or specialized job execution. The CLI enables installation as a system service, registration with a GitLab instance via token, listing/verifying runners, and service control (start/stop/restart).

Typical workflow: Download the binary from GitLab, gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner, then gitlab-runner register providing server URL, token, executor, tags, etc. Once running, runners handle concurrent jobs based on config limits.

Supports features like Docker volumes/machines, Kubernetes clusters, caching, and autoscaling. Logs and state are managed via flags. Ideal for Linux servers, it integrates with systemd for daemon management.

Commands like install, start, stop, restart require root/sudo.
Config file must have strict permissions (e.g., 0600).
Executors like Docker need group access (e.g., docker group).

register: Register runner with GitLab.
run: Run daemon in foreground.
list/status/verify: Inspect runners.
install/start/stop: Service management.

TOML format in /etc/gitlab-runner/config.toml.
Defines [[runners]] with executor, url, token, limit, variables.

gitlab-runner register --non-interactive --url https://gitlab.com/ --registration-token TOKEN --executor docker --docker-image alpine:latest --description my-runner

Released in 2014 with GitLab 7.0 for CI support. Evolved through GitLab 8+ with multi-executor support, Docker/K8s integration. Maintained by GitLab Inc., current v16.x (2024) emphasizes autoscaling, FFmpeg caching.

systemctl(1), journalctl(1), docker(1)