Add Docker executor support for a Windows version

GitLab supports specific versions of Windows .

To add support for a new Windows version for the Docker executor , you must release a helper image with the same Windows version. Then you can run the helper image on the Windows host OS.

To build the helper image for the version, you need GitLab Runner installed on that Windows version, because Windows requires your host OS and container OS versions to match.

Infrastructure

We must build the helper image for it to be used for the user job.

Create a base image for infrastructure to use

To add support for a new Windows version, you might need to create a new helper image. Windows versions can run older helper images (backward compatibility), or might require a newly built helper image. For compatibility details, see Windows container version compatibility

To support a new host OS environment or helper image, update the windows-containers repository to build a base image. The autoscaler uses the base image to build the GitLab Runner helper image.

For example, when adding support for Windows Server 2025, backward compatibility allowed reuse of the existing 2022 helper images. However, when adding support to Windows Server 2022, the Windows Server 2019 helper image was not compatible with process isolation, so a new image was required.

Some GCP base images require Docker installation during the build process. To update the CI/CD environment for a new image, update the following files:

  • .gitlab-ci.yml
  • .gitlab/ci/build.gitlab-ci.yml

Test the image generated

We recommend testing the image generated in the dev step. It is likely to be named dev xxx where xxx stands for the windows server version.

To test the image, the following steps can be followed:

  1. Add support for the new windows server version in GitLab Runner project and generate the gitlab-runner-helper.x86_64-windows.exe binary.
  2. Create a VM using the disk image generated during the dev step. When adding support for windows server ltsc2022 , the disk image name was runners-windows-21h1-core-containers-dev-40-mr
  3. Generate the gitlab-runner-helper Docker image from this VM. To do so, you need to download the gitlab-runner-helper.x86_64-windows.exe binary on the VM. As the Invoke-WebRequest PowerShell command might be unavailable, you should use the Start-BitsTransfer command instead.
  4. Create another VM using the new GCP windows server image to support.
  5. Install the gitlab-runner executable generated for the previously update GitLab-Runner project and register it to a project.
  6. Successfully launch a job.

An example of this procedure is summarized in this comment .

Publish the image

After we merge the merge request created from the previous step , we need to run the publish job manually for the image to be published to our production GCP project.

Take note of the image name that is created from the publish job, for example in this job we created an image called runners-windows-2019-core-containers-2020-07-17 . This will be used for the install part .

Add two new runner managers

At this point we should have a base image ready in our production environment, so we can use it inside the CI pipeline for the GitLab Runner project. The only thing that is left is to set up the Runner Managers.

Register

Run gitlab-runner register to register the two new runners. These should be project-specific runners, so we need to use the registration token from the project settings . The name of the runner should follow the same naming convention as the existing ones.

For example, for Windows Server Core 2004 we should name the Runner Managers the following:

  1. windows-2004-private-runner-manager-1
  2. windows-2004-private-runner-manager-2

Once registered, make sure you safely store the runner tokens found in the config.toml file since we are going to need these for the installation step.

Finally, we’ll need to assign the new Runner Managers to the security fork project and to the ’liveness’ test support project. So for each of the new Runner Managers:

  1. Go to the Runners section of the Runner project CI/CD settings page ;
  2. Unlock the new Runner by editing its properties and unchecking Lock to current projects ;
  3. For the security fork project:
    1. Go to the Runners section of the project’s CI/CD settings page ;
    2. Scroll down to the Other available runners section and enable the runner for this project;
  4. For the ’liveness’ test support project:
    1. Go to the Runners section of the project’s CI/CD settings page ;
    2. Scroll down to the Other available runners section and enable the runner for this project;
  5. Lock the Runner back again in the Runner project CI/CD settings page .

Install

Install a new instance of autoscaler to have a specific config.toml for that Windows version. We need to update our Ansible repository ( https://ops.gitlab.net/gitlab-com/gl-infra/ci-infrastructure-windows ) to include the new Windows version.

For example, if we want to add support for Windows Server Core 2004 in the 13.7 milestone we can see this merge request: https://ops.gitlab.net/gitlab-com/gl-infra/ci-infrastructure-windows/-/merge_requests/70 , where we update the following files:

  1. ansible/roles/runner/tasks/main.yml
  2. ansible/roles/runner/tasks/autoscaler.yml
  3. ansible/group_vars/gcp_role_runner_manager.yml
  4. ansible/host_vars/windows-shared-runners-manager-1.yml
  5. ansible/host_vars/windows-shared-runners-manager-2.yml

When opening a merge request make sure that the maintainer is aware that they need to register 2 new runners and save them inside the CI/CD variables with the keys defined in ansible/host_vars .

Publish registry.gitlab.com/gitlab-org/ci-cd/tests/liveness

The image registry.gitlab.com/gitlab-org/ci-cd/tests/liveness is used as part of the CI process for GitLab Runner . Make sure that an image based on the new Windows version is published.

For example, if we want to add support for Windows Server Core 2004 in the 13.7 milestone we can see the following merge request ,