Install GitLab Runner on Windows

To install and run GitLab Runner on Windows you need:

  • Git, which can be installed from the official site
  • A password for your user account, if you want to run it under your user account rather than the Built-in System Account.

Installation

cautionWith GitLab Runner 10, the executable was renamed to gitlab-runner. If you want to install a version prior to GitLab Runner 10, visit the old docs.
  1. Create a folder somewhere in your system, ex.: C:\GitLab-Runner.
  2. Download the binary for 64-bit or 32-bit and put it into the folder you created. The following assumes you have renamed the binary to gitlab-runner.exe (optional). You can download a binary for every available version as described in Bleeding Edge - download any other tagged release.
  3. Make sure to restrict the Write permissions on the GitLab Runner directory and executable. If you do not set these permissions, regular users can replace the executable with their own and run arbitrary code with elevated privileges.
  4. Run an elevated command prompt:
  5. Register a runner.
  6. Install GitLab Runner as a service and start it. You can either run the service using the Built-in System Account (recommended) or using a user account.

    Run service using Built-in System Account (under directory created in step 1. from above, ex.: C:\GitLab-Runner)

    cd C:\GitLab-Runner
    .\gitlab-runner.exe install
    .\gitlab-runner.exe start
    

    Run service using user account (under directory created in step 1. from above, ex.: C:\GitLab-Runner)

    You have to enter a valid password for the current user account, because it’s required to start the service by Windows:

    cd C:\GitLab-Runner
    .\gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD
    .\gitlab-runner.exe start
    

    See the troubleshooting section if you encounter any errors during the GitLab Runner installation.

  7. (Optional) Update the runner’s concurrent value in C:\GitLab-Runner\config.toml to allow multiple concurrent jobs as detailed in advanced configuration details. Additionally, you can use the advanced configuration details to update your shell executor to use Bash or PowerShell rather than Batch.

Voila! Runner is installed, running, and will start again after each system reboot. Logs are stored in Windows Event Log.

Update

  1. Stop the service (you need an elevated command prompt as before):

    cd C:\GitLab-Runner
    .\gitlab-runner.exe stop
    
  2. Download the binary for 64-bit or 32-bit and replace runner’s executable. You can download a binary for every available version as described in Bleeding Edge - download any other tagged release.

  3. Start the service:

    .\gitlab-runner.exe start
    

Uninstall

From an elevated command prompt:

cd C:\GitLab-Runner
.\gitlab-runner.exe stop
.\gitlab-runner.exe uninstall
cd ..
rmdir /s GitLab-Runner

Windows version support policy

We follow the same lifecycle policy as Microsoft’s Servicing Channels.

This means that we support:

  • Long-Term Servicing Channel, versions for 5 years after their release date. Note that we don’t support versions that are on extended support.
  • Semi-Annual Channel versions for 18 months after their release date. We don’t support these versions after mainstream support ends.

This is the case for both the Windows binaries that we distribute, and also for the Docker executor.

noteThe Docker executor for Windows containers has strict version requirements, because containers have to match the version of the host OS. See the list of supported Windows containers for more information.

After a Windows version no longer receives mainstream support from Microsoft, we officially deprecate the version and remove it in the next major change. For example, in 12.x we started supporting Windows 1803 because it came out on 2018-04-30. Mainstream support ended on 2019-11-12, so we deprecated Windows 1803 in 12.x and it was removed in GitLab 13.0.

As a single source of truth we use https://docs.microsoft.com/en-us/lifecycle/products/ which specifies both the release and mainstream support dates.

Below is a list of versions that are commonly used and their end of life date:

OS Mainstream support end of life date
Windows 10 1809/2019 January 2024
Windows Server Datacenter 1809/2019 January 2024
Windows Server Datacenter 1903 December 2020

Future releases

Microsoft releases new Windows Server products in the Semi-Annual Channel twice a year, and every 2 - 3 years a new major version of Windows Sever is released in the Long-Term Servicing Channel (LTSC).

GitLab aims to test and release new GitLab Runner helper images that include the latest Windows Server version (Semi-Annual Channel) within 1 month of the official Microsoft release date. Refer to the Windows Server current versions by servicing option list for availability dates.

Troubleshooting

Make sure that you read the FAQ section which describes some of the most common problems with GitLab Runner.

If you encounter an error like The account name is invalid try to add .\ before the username:

.\gitlab-runner.exe install --user ".\ENTER-YOUR-USERNAME" --password "ENTER-YOUR-PASSWORD"

If you encounter a The service did not start due to a logon failure error while starting the service, please look in the FAQ to check how to resolve the problem.

If you don’t have a Windows Password, the GitLab Runner service won’t start but you can use the Built-in System Account.

If you have issues with the Built-in System Account, please read Configure the Service to Start Up with the Built-in System Account on Microsoft’s support website.

Get runner logs

When you run .\gitlab-runner.exe install it installs gitlab-runner as a Windows service. You can find the logs in the Event Viewer with the provider name gitlab-runner.

If you don’t have access to the GUI, in PowerShell, you can run Get-WinEvent.

PS C:\> Get-WinEvent -ProviderName gitlab-runner

   ProviderName: gitlab-runner

TimeCreated                     Id LevelDisplayName Message
-----------                     -- ---------------- -------
2/4/2021 6:20:14 AM              1 Information      [session_server].listen_address not defined, session endpoints disabled  builds=0...
2/4/2021 6:20:14 AM              1 Information      listen_address not defined, metrics & debug endpoints disabled  builds=0...
2/4/2021 6:20:14 AM              1 Information      Configuration loaded                                builds=0...
2/4/2021 6:20:14 AM              1 Information      Starting multi-runner from C:\config.toml...        builds=0...