GitLab Runner commands

Tier:Free, Premium, Ultimate Offering:GitLab, Self-managed

GitLab Runner contains a set of commands you use to register, manage, and run your builds.

You can check the list of commands by executing: 

gitlab-runner--help

Append--helpafter a command to see its specific help page: 

gitlab-runner <command>--help

Using environment variables

Most of the commands support environment variables as a method to pass the configuration to the command.

You can see the name of the environment variable when invoking--helpfor a specific command. For example, you can see below the help message for therun command: 

gitlab-runner run--help

The output is similar to: 

NAME:
gitlab-runner run - run multi runner service

USAGE:
gitlab-runner run [command options] [arguments...]

OPTIONS:
-c, --config "/Users/ayufan/.gitlab-runner/config.toml" Config file [$CONFIG_FILE]

Running in debug mode

Debug mode is especially useful when looking for the cause of some undefined behavior or error.

To run a command in debug mode, prepend the command with--debug: 

gitlab-runner--debug<command>

Super-user permission

Commands that access the configuration of GitLab Runner behave differently when executed as super-user (root). The file location depends on the user executing the command.

When you executegitlab-runnercommands, you see the mode it is running in: 

$gitlab-runner run

INFO[0000] Starting multi-runner from /Users/ayufan/.gitlab-runner/config.toml...builds=0
WARN[0000] Runninginuser-mode.
WARN[0000] Usesudoforsystem-mode:
WARN[0000]$sudogitlab-runner...

You should useuser-modeif you are sure this is the mode you want to work with. Otherwise, prefix your command withsudo: 

$sudogitlab-runner run

INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml...builds=0
INFO[0000] Runninginsystem-mode.

In the case of Windows, you may need to run the command prompt as an administrator.

Configuration file

GitLab Runner configuration uses theTOMLformat.

You can find the file to be edited:

  1. On *nix systems when GitLab Runner is executed as super-user (root):/etc/gitlab-runner/config.toml
  2. On *nix systems when GitLab Runner is executed as non-root:~/.gitlab-runner/config.toml
  3. On other systems:./config.toml

Most of the commands accept an argument to specify a custom configuration file, so you can have a multiple different configurations on a single machine. To specify a custom configuration file, use the-cor--configflag, or use theCONFIG_FILEenvironment variable.

Signals

You can use system signals to interact with GitLab Runner. The following commands support the following signals:

Command Signal Action
register SIGINT Cancel runner registration and delete if it was already registered.
run,run-single SIGINT,SIGTERM Abort all running builds and exit as soon as possible. Use twice to exit now (forceful shutdown).
run,run-single SIGQUIT Stop accepting a new builds. Exit as soon as currently running builds do finish (graceful shutdown).
run SIGHUP Force to reload configuration file.

For example, to force a reload of a runner’s configuration file, run: 

sudo kill-SIGHUP<main_runner_pid>

Forgraceful shutdowns: 

sudo kill-SIGQUIT<main_runner_pid>
caution
Donotusekillallorpkillfor graceful shutdowns if you are usingshell ordockerexecutors. This can cause improper handling of the signals due to subprocessess being killed as well. Use it only on the main process handling the jobs.

If your operating system is configured to automatically restart the service if it fails (which is the default on some platforms) it may automatically restart the runner if it’s shut down by the signals above.

Commands overview

You see the following if you rungitlab-runnerwithout any arguments: 

NAME:
gitlab-runner - a GitLab Runner

USAGE:
gitlab-runner [global options] command [command options] [arguments...]

VERSION:
16.5.0 (853330f9)

AUTHOR:
GitLab Inc. <support@gitlab >

COMMANDS:
list List all configured runners
run run multi runner service
register register a new runner
reset-token reset a runner's token
install install service
uninstall uninstall service
start start service
stop stop service
restart restart service
status get status of a service
run-single start single runner
unregister unregister specific runner
verify verify all registered runners
artifacts-downloader download and extract build artifacts (internal)
artifacts-uploader create and upload build artifacts (internal)
cache-archiver create and upload cache artifacts (internal)
cache-extractor download and extract cache artifacts (internal)
cache-init changed permissions for cache paths (internal)
health-check check health for a specific address
read-logs reads job logs from a file, used by kubernetes executor (internal)
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:
--cpuprofile value write cpu profile to file [$CPU_PROFILE]
--debug debug mode [$RUNNER_DEBUG]
--log-format value Choose log format (options: runner, text, json) [$LOG_FORMAT]
--log-level value, -l value Log level (options: debug, info, warn, error, fatal, panic) [$LOG_LEVEL]
--help, -h show help
--version, -v print the version

Below we explain what each command does in detail.

Use the following commands to register a new runner, or list and verify them if they are still registered.

These commands support the following arguments:

Parameter Default Description
--config See theconfiguration file section Specify a custom configuration file to be used

gitlab-runner register

This command registers your runner in GitLab by using the GitLabRunners API.

The registered runner is added to theconfiguration file. You can use multiple configurations in a single installation of GitLab Runner. Executing gitlab-runner registeradds a new configuration entry. It doesn’t remove the previous ones.

There are two options to register a runner:

  • interactive.
  • non-interactive.
note
Runners can be registered directly by using the GitLabRunners APIbut configuration is not generated automatically.

Interactive registration

This command is usually used in interactive mode (default). You are asked multiple questions during a runner’s registration.

This question can be pre-filled by adding arguments when invoking the registration command: 

gitlab-runner register--namemy-runner--url"http://gitlab.example"--tokenmy-authentication-token

Or by configuring the environment variable before theregistercommand: 

exportCI_SERVER_URL=http://gitlab.example
exportRUNNER_NAME=my-runner
exportCI_SERVER_TOKEN=my-authentication-token
gitlab-runner register

To check all possible arguments and environments execute: 

gitlab-runner register--help

Non-interactive registration

It’s possible to use registration in non-interactive / unattended mode.

You can specify the arguments when invoking the registration command: 

gitlab-runner register--non-interactive<other-arguments>

Or by configuring the environment variable before theregistercommand: 

<other-environment-variables>
exportREGISTER_NON_INTERACTIVE=true
gitlab-runner register
note
Boolean parameters must be passed in the command line with--key={true|false}.

[[runners]]configuration template file

History

Additional options can be easily configured during runner registration using the configuration template filefeature.

gitlab-runner list

This command lists all runners saved in the configuration file.

gitlab-runner verify

This command checks if the registered runners can connect to GitLab, but it doesn’t verify if the runners are being used by the GitLab Runner service. An example output is: 

Verifying runner... is alive runner=fee9938e
Verifying runner... is alive runner=0db52b31
Verifying runner... is alive runner=826f687f
Verifying runner... is alive runner=32773c0f

To remove the old runners that have been removed from GitLab, execute the following command.

caution
This operation cannot be undone. It updates the configuration file, so make sure to have a backup ofconfig.tomlbefore executing it.
gitlab-runner verify--delete

gitlab-runner unregister

This command unregisters registered runners by using the GitLabRunners API.

It expects either:

  • A full URL and the runner’s token.
  • The runner’s name.

With the--all-runnersoption, it unregisters all the attached runners.

note
Runners can be unregistered with the GitLabRunners APIbut the configuration is not modified for the user.
  • If the runner was created with a runner registration token,gitlab-runner unregister with the runner authentication token deletes the runner.
  • If the runner was created in the GitLab UI or with the Runners API,gitlab-runner unregister with the runner authentication token deletes the runner manager, but not the runner. To completely remove the runner,delete the runner in the runners administration page or use theDELETE /runnersREST API endpoint.

To unregister a single runner, first get the runner’s details by executing gitlab-runner list: 

test-runner Executor=shell Token=t0k3n URL=http://gitlab.example

Then use this information to unregister it, using one of the following commands.

caution
This operation cannot be undone. It updates the configuration file, so make sure to have a backup ofconfig.tomlbefore executing it.

By URL and token 

gitlab-runner unregister--url"http://gitlab.example /"--tokent0k3n

By name 

gitlab-runner unregister--nametest-runner
note
If there is more than one runner with the given name, only the first one is removed.

All runners 

gitlab-runner unregister--all-runners

gitlab-runner reset-token

This command resets a runner’s token by using the GitLab Runners API, with either therunner ID or thecurrent token.

It expects the runner’s name (or URL and ID), and an optional PAT if resetting by runner ID. The PAT and runner ID are intended to be used if the token has already expired.

With the--all-runnersoption, it resets all the attached runners’ tokens.

With runner’s current token 

gitlab-runner reset-token--nametest-runner

With PAT and runner name 

gitlab-runner reset-token--nametest-runner--patPaT

With PAT, GitLab URL, and runner ID 

gitlab-runner reset-token--url"https://gitlab.example /"--id12345--patPaT

All runners 

gitlab-runners reset-token--all-runners

The following commands allow you to manage the runner as a system or user service. Use them to install, uninstall, start, and stop the runner service.

All service related commands accept these arguments:

Parameter Default Description
--service gitlab-runner Specify custom service name
--config See theconfiguration file Specify a custom configuration file to use

gitlab-runner install

This command installs GitLab Runner as a service. It accepts different sets of arguments depending on which system it’s run on.

When run onWindowsor as super-user, it accepts the--userflag which allows you to drop privileges of builds run with theshellexecutor.

Parameter Default Description
--service gitlab-runner Specify service name to use
--config See theconfiguration file Specify a custom configuration file to use
--syslog true(for non systemd systems) Specify if the service should integrate with system logging service
--working-directory the current directory Specify the root directory where all data is stored when builds are run with theshellexecutor
--user root Specify the user that executes the builds
--password none Specify the password for the user that executes the builds

gitlab-runner uninstall

This command stops and uninstalls GitLab Runner from being run as an service.

gitlab-runner start

This command starts the GitLab Runner service.

gitlab-runner stop

This command stops the GitLab Runner service.

gitlab-runner restart

This command stops and then starts the GitLab Runner service.

gitlab-runner status

This command prints the status of the GitLab Runner service. The exit code is zero when the service is running and non-zero when the service is not running.

Multiple services

By specifying the--serviceflag, it is possible to have multiple GitLab Runner services installed, with multiple separate configurations.

This command allows to fetch and process builds from GitLab.

gitlab-runner run

This is main command that is executed when GitLab Runner is started as a service. It reads all defined runners fromconfig.tomland tries to run all of them.

The command is executed and works until itreceives a signal.

It accepts the following parameters.

Parameter Default Description
--config Seeconfiguration-file Specify a custom configuration file to be used
--working-directory the current directory Specify the root directory where all data is stored when builds run with theshellexecutor
--user the current user Specify the user that executes builds
--syslog false Send all logs to SysLog (Unix) or EventLog (Windows)
--listen-address empty Address (<host>:<port>) on which the Prometheus metrics HTTP server should be listening

gitlab-runner run-single

History
  • Ability to use a configuration fileintroducedin GitLab Runner 17.1.

This is a supplementary command that can be used to run only a single build from a single GitLab instance. It can:

  • Take all options either as CLI parameters or environment variables, including the GitLab URL and Runner token. For example, a single job with all parameters specified explicitly: 

    gitlab-runner run-single-uhttp://gitlab.example-tmy-runner-token--executordocker--docker-imageruby:2.7

  • Read from a configuration file to use a specific runner’s configuration. For example, a single job with a configuration file: 

    gitlab-runner run-single-c~/.gitlab-runner/config.toml-rrunner-name

You can see all possible configuration options by using the--helpflag: 

gitlab-runner run-single--help

You can use the--max-buildsoption to control how many builds the runner executes before exiting. The default of0means that the runner has no build limit and jobs run forever.

You can also use the--wait-timeoutoption to control how long the runner waits for a job before exiting. The default of0means that the runner has no timeout and waits forever between jobs.

Internal commands

GitLab Runner is distributed as a single binary and contains a few internal commands that are used during builds.

gitlab-runner artifacts-downloader

Download the artifacts archive from GitLab.

gitlab-runner artifacts-uploader

Upload the artifacts archive to GitLab.

gitlab-runner cache-archiver

Create a cache archive, store it locally or upload it to an external server.

gitlab-runner cache-extractor

Restore the cache archive from a locally or externally stored file.

Troubleshooting

Below are some common pitfalls.

Usually theservice related commandsrequire administrator privileges:

  • On Unix (Linux, macOS, FreeBSD) systems, prefixgitlab-runnerwithsudo
  • On Windows systems use the elevated command prompt. Run anAdministratorcommand prompt. The simplest way is to writeCommand Promptin the Windows search field, right click and selectRun as administrator.You are asked to confirm that you want to execute the elevated command prompt.

gitlab-runner stopdoesn’t shut down gracefully

When a runner is installed on a host and runs local executors, it starts additional processes for some operations, like downloading or uploading artifacts, or handling cache. These processes are executed asgitlab-runnercommands, which means that you can usepkill -QUIT gitlab-runner orkillall QUIT gitlab-runnerto kill them. When you kill them, the operations they are responsible for fail.

Here are two ways to prevent this:

  • Register the runner as a local service (likesystemd) withSIGQUITas the kill signal, and usegitlab-runner stoporsystemctl stop gitlab-runner.service. Here is an example configuration to enable this behavior: 

    ;/etc/systemd/system/gitlab-runner.service.d/kill.conf
[Service]
KillSignal=SIGQUIT
TimeoutStopSec=infinity
    • To apply the configuration change, after you create this file, reloadsystemdwithsystemctl daemon-reload.

  • Manually kill the process withkill -SIGQUIT <pid>.You have to find thepid of the maingitlab-runnerprocess. You can find this by looking at logs, as it’s displayed on startup: 

    $gitlab-runner run
Runtime platformarch=arm64os=linuxpid=8revision=853330f9version=16.5.0

Saving system ID state file: access denied

GitLab Runner 15.7 and 15.8 might not start if it lacks write permissions for the directory that contains theconfig.tomlfile.

When GitLab Runner starts, it searches for the.runner_system_idfile in the directory that contains theconfig.toml.If it cannot find the.runner_system_idfile, it creates a new one. If GitLab Runner doesn’t have write permissions, it fails to start.

To resolve this issue, temporarily allow file write permissions, then rungitlab-runner run. After the.runner_system_idfile is created, you can reset the permissions to read-only.