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 [options]

register
    Registers a new runner with a GitLab instance. Asks for the GitLab instance URL and registration token.

run
    Starts the runner and listens for jobs from the GitLab instance.

install
    Installs the gitlab-runner service on the system.

uninstall
    Uninstalls the gitlab-runner service.

start
    Starts the gitlab-runner service.

stop
    Stops the gitlab-runner service.

restart
    Restarts the gitlab-runner service.

status
    Shows the status of the gitlab-runner service.

unregister
    Unregisters a runner from a GitLab instance.

verify
    Verifies the configuration of a runner.

list
    Lists all configured runners.

config
    Prints the current runner configuration.

--version
    Show version information.

--help
    Show help message.

The gitlab-runner command is the official GitLab Runner command-line interface. It's the application that executes your CI/CD jobs in GitLab. It provides the environment and executes the scripts defined in your .gitlab-ci.yml file. GitLab Runner can be installed and configured on various operating systems and architectures and registered to one or more GitLab instances. gitlab-runner can execute builds concurrently using different executors (e.g., shell, Docker, virtual machines, Kubernetes). It's the core component enabling automated testing, builds, and deployments as part of your CI/CD pipeline. Using this command, you manage the lifecycle of a runner: install, configure, register, start, stop, and manage the runner's configuration. The command provides sub-commands for almost all possible tasks related to runners. Each runner executes jobs independent of other runners, even if they use the same executor, enabling high-throughput and scalability.

Proper configuration and network access to the GitLab instance are critical for the runner to function correctly. The config.toml file is very important; ensure it is backed up, as it contains sensitive registration tokens. Security considerations are crucial when using shell executors.

The runner's configuration is stored in a file named config.toml, located typically in /etc/gitlab-runner/ (Linux). This file defines the runners, their executors, and other important settings. It must be configured carefully to avoid issues when running CI/CD jobs. Make sure the user has the rights to read/write to config file.

GitLab Runner supports various executors, including shell, Docker, SSH, VirtualBox, Parallels, Kubernetes, and more. Each executor has its own requirements and configuration options. Docker executor is one of the most popular due to the easiness to set the environment.

On Linux systems, gitlab-runner typically runs as a system service. The install, start, stop, restart and status commands are used to manage this service. You should ensure that the service is properly configured and running for the runner to receive and execute jobs.

gitlab-runner has evolved significantly since its initial release. It has gone from supporting basic shell executors to offering sophisticated integrations with Docker, Kubernetes, and virtual machines. The core aim has always been to provide a robust and scalable solution for executing CI/CD jobs, adapting to the changing needs of modern software development workflows.

Initially, it was designed to handle simple build processes but has since expanded to support complex deployment pipelines and testing scenarios. The continuous development has focused on improving performance, security, and ease of use, making it a critical tool in the DevOps ecosystem.

docker(1), kubectl(1)