GitLab Runner FAQ

What does coordinator mean?

The coordinator is the GitLab installation from which a job is requested.

In other words, runners are isolated (virtual) machines that pick up jobs
requested by their coordinator.

Where are logs stored when run as a service?

If the GitLab Runner is run as service on Linux/OSX the daemon logs to syslog.

If the GitLab Runner is run as service on Windows it logs to System's Event Log.

Run in --debug mode

Is it possible to run GitLab Runner in debug/verbose mode. From a terminal, do:

gitlab-runner --debug run

I get a PathTooLongException during my builds on Windows

This is caused by tools like npm which will sometimes generate directory structures
with paths more than 260 characters in length. There are two possible fixes you can
adopt to solve the problem.

a) Use Git with core.longpaths enabled

You can avoid the problem by using Git to clean your directory structure, first run
git config --system core.longpaths true from the command line and then set your
project to use git fetch from the GitLab CI project settings page.

b) Use NTFSSecurity tools for PowerShell

The NTFSSecurity PowerShell module provides
a Remove-Item2 method which supports long paths. The Gitlab CI Multi Runner will
detect it if it is available and automatically make use of it.

I'm seeing x509: certificate signed by unknown authority

I get Permission Denied when accessing the /var/run/docker.sock

If you want to use Docker executor,
and you are connecting to Docker Engine installed on server.
You can see the Permission Denied error.
The most likely cause is that your system uses SELinux (enabled by default on CentOS, Fedora and RHEL).
Check your SELinux policy on your system for possible denials.

My gitlab runner is on Windows. How can I get colored output on the web terminal?

Short answer:

Make sure that you have the ANSI color codes in your program's output. For the purposes of text formatting, assume that you're
running in a UNIX ANSI terminal emulator (because that's what the webUI's output is).

Long Answer:

The web interface for gitlab-ci emulates a UNIX ANSI terminal (at least partially). The gitlab-runner pipes any output from the build
directly to the web interface. That means that any ANSI color codes that are present will be honored.

Windows' CMD terminal (before Win10 (source))
does not support ANSI color codes - it uses win32 (ANSI.SYS) calls instead which are not present in
the string to be displayed. When writing cross-platform programs, a developer will typically use ANSI color codes by default and convert
them to win32 calls when running on a Windows system (example: Colorama).

If your program is doing the above, then you need to disable that conversion for the CI builds so that the ANSI codes remain in the string.

"warning: You appear to have cloned an empty repository."

When running git clone using HTTP(s) (with GitLab Runner or manually for
tests) and you see the following output:

$ git clone https://git.example.com/user/repo.git
Cloning into 'repo'...
warning: You appear to have cloned an empty repository.

Make sure, that the configuration of the HTTP Proxy in your GitLab server
installation is done properly. Especially if you are using some HTTP Proxy with
its own configuration, make sure that GitLab requests are proxied to the
GitLab Workhorse socket, not to the GitLab unicorn socket.

Git protocol via HTTP(S) is resolved by the GitLab Workhorse, so this is the
main entrypoint of GitLab.

The first command enables access to developer tools for your user.
The second command allows the user who is member of the developer group to
do UI interactions, e.g., run the iOS simulator.

Make sure that your Runner service doesn't use SessionCreate = true.
Previously, when running GitLab Runner as a service, we were creating
LaunchAgents with SessionCreate. At that point (Mavericks), this was
the only solution to make Code Signing work. That changed recently with
OSX El Capitan which introduced a lot of new security features that
altered this behavior.
Since GitLab Runner 1.1, when creating a LaunchAgent, we don't set
SessionCreate. However, in order to upgrade, you need to manually
reinstall the LaunchAgent script:

gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

Then you can verify that ~/Library/LaunchAgents/gitlab-runner.plist has
SessionCreate set to false.

The service did not start due to a logon failure error when starting service on Windows

When installing and starting the GitLab Runner service on Windows you can
meet with such error:

$ gitlab-runner install --password WINDOWS_MACHINE_PASSWORD
$ gitlab-runner start
$ FATA[0000] Failed to start GitLab Runner: The service did not start due to a logon failure.

This error can occur when the user used to execute the service doesn't have
the SeServiceLogonRight permission. In such case you need to add this
permission for the chosen user and then try to start the service again.

You can add SeServiceLogonRight in two ways:

Manually using Administrative Tools:

Go to Control Panel > System and Security > Administrative Tools,

open the Local Security Policy tool,

chose the Security Settings > Local Policies > User Rights Assignment on the
list on the left,

open the Log on as a service on the list on the right,

click on the Add User or Group... button,

add the user ("by hand" or using Advanced... button) and apply the settings.

execute ntrights.exe ntrights +r SeServiceLogonRight -u USER_NAME_HERE (remember,
that you should provide a full path for ntrights.exe executable or add that
path to system's PATH environment variable).

Notice: The tool was created in 2003 and was initially designed to use
with Windows XP and Windows Server 2003. On Microsoft sites
you can find an example of usage Ntrights.exe that applies to Windows 7 and Windows Server 2008 R2.
This solution is not tested and because of the age of the software it may not work
on newest Windows versions.

After adding the SeServiceLogonRight for the user used in service configuration,
the command gitlab-runner start should finish without failures
and the service should be started properly.

zoneinfo.zip: no such file or directory error when using OffPeakTimezone

In v1.11.0 we made it possible to configure the timezone in which OffPeakPeriods
are described. This feature should work on most Unix systems out of the box. However on some
Unix systems, and probably on most non-Unix systems (including Windows, for which we're providing
Runner's binaries), when used, the Runner will crash at start with an error similar to:

Failed to load config Invalid OffPeakPeriods value: open /usr/local/go/lib/time/zoneinfo.zip: no such file or directory

The error is caused by the time package in Go. Go uses the IANA Time Zone database to load
the configuration of the specified timezone. On most Unix systems, this database is already present on
one of well-known paths (/usr/share/zoneinfo, /usr/share/lib/zoneinfo, /usr/lib/locale/TZ/).
Go's time package looks for the Time Zone database in all those three paths. If it doesn't find any
of them, but the machine has a configured Go development environment (with a proper $GOPATH
present for Runner's process), then it will fallback to the $GOROOT/lib/time/zoneinfo.zip file.

If none of those paths are present (for example on a production Windows host) the above error is thrown.

In case your system has support for the IANA Time Zone database, but it's not available by default, you
can try to install it. For Linux systems it can be done for example by:

If your system doesn't provide this database in a native way, then you can make OffPeakTimezone
working by following the steps below:

Downloading the zoneinfo.zip. Starting with version v9.1.0 you can download
the file from a tagged path. In that case you should replace latest with the tag name (e.g., v9.1.0)
in the zoneinfo.zip download URL.

Store this file in a well known directory. We're suggesting to use the same directory where
the config.toml file is present. So for example, if you're hosting Runner on Windows machine
and your config file is stored at C:\gitlab-runner\config.toml, then save the zoneinfo.zip
at C:\gitlab-runner\zoneinfo.zip.

Set the ZONEINFO environment variable containing a full path to the zoneinfo.zip file. If you
are starting the Runner using the run command, then you can do this with:

If you are starting the Runner as a system service then you will need to update/override
the service configuration in a way that is provided by your service manager software
(unix systems) or by adding the ZONEINFO variable to the list of environment variables
available for Runner's user through System Settings (Windows).