[ notes to myself ]

Set up GitLab Runner for Windows containers

3 min read

Quick notes on installing/configuring Gitlab Runner on Windows Server 2022 to support Windows container workloads

Install Git

  • Grab and run the installer from git-scm.com/downloads/win.
  • Deselect the options for Windows Explorer integration, file associations, and the Scalar add-on.
  • Choose Notepad as the default editor just so we aren’t creating other weird dependencies.
  • Set the default branch name to main (probably not required but let’s be consistent with modern norms).
  • Pick the recommended Git from the command line and also from 3rd-party software option for PATH handling.
  • Use the external OpenSSH since that’s built-in to Windows these days.
  • Use the native Windows Secure Channel library.
  • I guess do Checkout as-is, commit as-is so that Git isn’t interfering with existing line endings and things.
  • Select Windows’ default console window to avoid installing anything new/weird.
  • Fast-forward or merge is an acceptable git pull option.
  • Don’t bother with configuring a Credential Manager since we’re not actually going to be interacting with Git directly.
  • Select the default Enable file system caching option.
  • Finally hit Install.

Install Docker CE

Note: You need Docker Desktop or Hyper-V or some other virtualization scheme if you want to run Linux containers on a Windows machine, but the light(er)weight Docker daemon is all that’s really for running Windows on Windows.

Per the Windows Server docs:

Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1
.\install-docker-ce.ps1

You’ll need to reboot to complete the installation. After the reboot, you can docker run --rm hello-world to verify that things are working.

Install GitLab Runner

Per the GitLab Docs:

  • Create runner directory: 
    New-Item -Path "C:\" -Name "GitLab-Runner" -ItemType "Directory"
  • Download the runner binary (x64) to that location and rename it to gitlab-runner.exe
  • Create the runner configuration in GitLab, maybe give it a tag to designate it as a Windows runner
  • Copy the registration command and run it in an elevated powershell session from the C:\GitLab-Runner\ directory: 
    .\gitlab-runner.exe register --url https://gitlab.example.com --token $token
  • Select the docker-windows executor.
  • Pick a preferred default image, like perhaps mcr.microsoft.com/windows/nanoserver:ltsc2022.
  • Install and start the runner service: 
    .\gitlab-runner.exe install
.\gitlab-runner.exe start
  • Edit C:\GitLab-Runner\config.toml as needed to adjust options like replacing the helper_image with an internally-hosted one if you can’t reach the public GitLab registry for some reason. (You’ll need to C:\GitLab-Runner\gitlab-runner.exe restart to reapply the config after a change.)

Example config.toml

(with some boring/default stuff omitted)

[[runners]]
  name = "My Windows Runner"
  url = "https://gitlab.example.com"
  id = 69 # very nice
  executor = "docker-windows"
  shell = "powershell" # default 'pwsh' may not be available on default WS2022 install/image
  [runners.docker]
    tls_verify = true
    image = "harbor.example.com/mcr/windows/nanoserver:ltsc2022" # use a locally-cached image
    privileged = false
    helper_image = "harbor.example.com/dockerhub/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}-servercore21H2"