gitlab-runner

Register a new runner

$ sudo gitlab-runner register

$ gitlab-runner list

$ sudo gitlab-runner start

$ sudo gitlab-runner stop

$ gitlab-runner run-single -u [gitlab_url] -t [token] --executor [shell]

$ gitlab-runner verify

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

$ gitlab-runner status

gitlab-runner command [options]

gitlab-runner is the agent that runs CI/CD jobs for GitLab. It connects to a GitLab instance, receives job requests, executes them in isolated environments, and reports results back. Runners can be shared across projects or dedicated to specific ones.
The runner supports multiple executors: shell (directly on host), docker (in containers), docker-machine (auto-scaled Docker), kubernetes (in K8s pods), virtualbox, parallels, and ssh. The Docker executor is most common for isolated, reproducible builds.
Registration requires a GitLab URL and registration token from the project/group/admin CI settings. Runners can operate as a system service or run in the foreground for debugging.

register

Register a new runner with GitLab instance.

List all configured runners.

Start the runner service.

Stop the runner service.

Restart the runner service.

Show runner service status.

Run the runner in foreground.

Run a single build for testing.

Verify runner connections to GitLab.

Remove a runner from GitLab.

Install as system service.

Remove system service.

Enable debug logging.

Use alternate config file.

Set custom working directory.

/etc/gitlab-runner/config.toml

Main configuration file where each registered runner appears as a `[[runners]]` section with its URL, token, executor, and settings.

Shell executor provides no isolation between jobs. Docker executor requires Docker installed. Registration tokens should be kept secret. Runners have access to whatever secrets are passed to jobs. Resource limits should be configured to prevent runaway jobs.

GitLab Runner was developed by GitLab Inc. as part of their CI/CD platform, which became part of GitLab around 2015 when GitLab CI was integrated into the main product. The runner has evolved from simple shell execution to supporting multiple sophisticated executors, making it one of the most versatile CI job runners available.

docker(1), gitlab-ctl(8), jenkins(1), github-actions(1)