Best practices

Below are some guidelines you should follow when you use and administer GitLab Runner.

Build Directory

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:

  • Kubernetes, Docker and Docker Machine executors it will be /builds inside of the container.
  • Shell executor it will be $PWD/builds.
  • SSH, VirtualBox and Parallels executors it will be ~/builds in 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 builds_dir setting.

Tip: You can also specify GIT_CLONE_PATH if 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 {builds_dir}/$RUNNER_TOKEN_KEY/$CONCURRENT_ID/$NAMESPACE/$PROJECT_NAME. For example: /builds/2mn-ncv-/0/user/playground.

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 place.