Below are some guidelines you should follow when you use and administer GitLab Runner.
GitLab Runner will clone the repository to a path that exists under a base path better known as the Builds Directory. The default location of this base directory depends on the executor. For:
Docker and Docker
Machine executors it will be
/buildsinside of the container.
Shell executor it will be
and Parallels executors it will be
~/buildsin the home directory of the user configured to handle the SSH connection to the target machine.
- Custom executor no default is provided and it must be explicitly configured, otherwise, the job will fail.
The used Builds Directory may be defined explicitly by the user with the
GIT_CLONE_PATHif you want to clone to a custom directory, and the guideline below doesn’t apply.
GitLab Runner will use the Builds Directory for all the Jobs that it
will run, but nesting them using a specific pattern
GitLab Runner does not stop you from storing things inside of the
Builds Directory. For example, you can store tools inside of
/builds/tools that can be used during CI execution. We HIGHLY
discourage this, you should never store anything inside of the Builds
Directory. GitLab Runner should have total control over it and does not
provide stability in such cases. If you have dependencies that are
required for your CI, we recommend installing them in some other
When the runner is installed on a host and runs local executors it will start additional processes for some operations,
like downloading or uploading artifacts, or handling cache.
These processes are executed as
gitlab-runner commands, which means that using
pkill -QUIT gitlab-runner or
killall QUIT gitlab-runner can kill them as well, and the operations they are responsible for will fail.
Here are two ways to prevent this:
Register the runner as a local service (like
SIGQUITas the kill signal, and use
systemctl stop gitlab-runner.service. Here is an example from the configuration of the shared runners on GitLab.com:
; /etc/systemd/system/gitlab-runner.service.d/kill.conf [Service] KillSignal=SIGQUIT TimeoutStopSec=__REDACTED__
Manually kill the process with
kill -SIGQUIT <pid>. You have to find the
pidof the main
gitlab-runnerprocess. You can find this by looking at logs, as it’s displayed on startup:
$ gitlab-runner run Runtime platform arch=amd64 os=linux pid=87858 revision=8d21977e version=12.10.0~beta.82.g8d21977e