Skip to content

WIP: Provide initial support for windows in docker executor


The docker executor has been updated to provide initial support for docker containers on windows. The executor works, but has some limitations:

  • We have included a Dockerfile to create the windows helper image. The helper image is not compiled into the runner using bindata due to the size of Windows container. At the moment, when using the default helper, it must be present locally.
    • The behavior of getPrebuiltImage() on windows is different from linux. If the image does not exist locally, it will try to pull from remote. Since the current name does not point to a public repository, this will always fail.
    • We'd like to propose changing the default helper name/tag to match a public repository. We could then alter the behavior of getPrebuiltImage() so that it does: 1) Looks for image locally, 2) Tries to extract from bindata (linux only), 3) Pulls from public repository (linux and windows)
    • The helper_image option has been added to the docker executor config options. This allows someone configuring the runner to point to a different helper image (it looks locally then tries to pull the specified image). This works on both linux and windows. The intention of this is to provide a publically available helper image for windows, so that users do not need to build the image from source or pull and retag into the standard helper image name. The behavior of this command is to look for the specified image locally and then try to pull from remote repository.
  • Services have been disabled on windows (it shows a warning if you attempt to use them). The linking functionality used to enable services does not work in windows.
    • Since linking has been deprecated, we'd like to propose moving the Services functionality to not use linking. This would enable windows to support services as well.
  • Windows requires Docker API version 1.24. A windows-only consts_windows.go file has been created to set the required API to 1.24 on windows, while leaving it at 1.18 for other platforms.
  • Windows containers currently have an issue where some applications (in our case, git) cannot write to mapped volumes. Our windows helper was unable to do git clone-type commands due to this. As a workaround, when the docker executor is used on windows, then internally it calls git clone-type commands and clones into a temporary directory. The files are then moved into the mapped volume. There is no user impact to this, it just required us to implement workarounds in shells/abstract.go. These workarounds are windows-only.
  • The build output is currently very verbose. Due to the way Windows output to stdout is handled for PowerShell, you see both the input commands and the output - this is very long, since it included setting all of the environement variables. There's also a potential pitfall if someone supplies a command that requires interaction (i.e. calling Get-Credential), where it will not be handled properly. The ideal scenario would be for the -NonInteractive switch invoking powershell.exe to work when sending commands (right now, it appears to be ignored if not also using -File or -Command) - this would solve both the stdout problem and the interaction problem. This has been resolved. See

Various fixes related to handling docker for windows have also been implemented. Where they may be impactful, they've been wrapped in a conditional check (runtime.GOOS == "windows").

We have performed manual testing of the executor on both windows and linux. Unit tests for the docker executor continue to pass. We've had some initial discussions about implementing windows-specific tests into the gitlab-ci.yml file, but have not yet done so.

Build prebuilt image

We have added a script (make-windows-container.ps1 in the root of the repo) that will build the prebuilt container. Right now, due to the limitations above, this needs to be done on the runner machine (which requires the gitlab runner source code), which is not ideal. To avoid this, in the runner TOML in the docker section, you can specify helper_image and point to our publically available image: cdhunt/gitlab-runner-helper:winx86_64-latest.

Does this MR meet the acceptance criteria?

  • Documentation has not been updated yet - we wanted to get feedback prior to completing that, in case the design needs to change.
  • The build is not currently passing to due to complexity checks - I do not see obvious ways to make this simpler for the affected methods, other than refactoring portions of the code into different methods. We want to solicit feedback on this.

What are the relevant issue numbers?

Edited by username-removed-1463092

Merge request reports