GitLab Continuous Integration for Windows Ecosystems

The integration of Windows environments into GitLab Continuous Integration (CI) pipelines represents a critical bridge between cross-platform development and platform-specific deployment requirements. While Linux has traditionally been the dominant environment for CI/CD, the necessity for building .NET frameworks, interacting with Windows-specific APIs, and executing GUI-based automation has led to a sophisticated infrastructure of hosted and self-managed Windows runners. This ecosystem allows developers to leverage the full power of Windows Server and desktop environments while maintaining the version control and orchestration capabilities of GitLab. The transition to Windows-based CI involves navigating specific architectural constraints, such as the distinction between interactive and non-interactive sessions, the nuances of PowerShell as a primary shell, and the operational differences between virtual machine-based hosted runners and containerized environments.

Hosted Windows Runners on GitLab.com

GitLab provides a managed solution for Windows environments through hosted runners, which are currently available in a beta state. These runners remove the overhead of server maintenance, allowing teams to execute jobs without managing their own hardware or virtual machines.

Machine Specifications and Resource Allocation

For users opting for the hosted service, GitLab offers a specific machine type designed to handle standard Windows build workloads. This ensures a predictable environment for resource planning.

The allocation of 2 vCPUs and 7.5 GB of memory provides a baseline for compiling moderate projects, while 75 GB of storage ensures that large dependency caches and build artifacts do not prematurely exhaust the disk space.

Supported Operating Systems and Shell Environments

The hosted fleet currently supports Windows 2022 in General Availability (GA). This ensures that jobs are running on a modern, secure, and supported version of the Windows Server OS.

A critical technical detail for users of hosted Windows runners is the shell configuration. Unlike Linux runners that typically default to Bash, hosted Windows runners are configured with PowerShell as the shell. This means that every command defined in the script section of the .gitlab-ci.yml file must be valid PowerShell syntax.

Implementation via .gitlab-ci.yml

To successfully route a job to the hosted Windows infrastructure, the tags keyword must be used to specify the saas-windows-medium-amd64 runner. Failure to include this tag, or using incorrect tags (such as mixing shared-windows with the SaaS tag), will result in the job being picked up by the default Linux runners, leading to catastrophic failures when Windows-specific commands like dir or dotnet are invoked in a Bash environment.

Example configuration for a Windows-based pipeline:

```yaml
.windowsjob:
tags:
- saas-windows-medium-amd64
beforescript:
- Set-Variable -Name "time" -Value (date -Format "%H:%m")
- echo ${time}
- echo "started by ${GITLABUSERNAME} / @${GITLABUSERLOGIN}"

build:
extends:
- .windows_job
stage: build
script:
- echo "running scripts in the build job"

test:
extends:
- .windows_job
stage: test
script:
- echo "running scripts in the test job"
```

Operational Constraints of Hosted Runners

Users should be aware of the provisioning latency associated with the beta phase. The average time to provision a new Windows virtual machine (VM) is approximately five minutes. This latency can lead to perceived slower start times for builds compared to the near-instantaneous startup of Linux containers.

Furthermore, it is important to clarify the architectural nature of these runners. Hosted Windows runners operate within virtual machines, not containers. This distinction is vital for developers who need to invoke system-level tools like dotnet-core or nuget, which are pre-installed in the VM image.

Self-Managed GitLab Runner Installation on Windows

For organizations requiring deeper control over the environment, or those needing to run GUI tests, installing a local GitLab Runner on a Windows machine is the required path.

Prerequisites for Installation

Before initiating the installation process, several system requirements must be met to ensure stability and compatibility:

• Git installation from the official source.
• A user account password (required if the runner is not using the Built-in System Account).
• System locale must be set to English (United States) to prevent character encoding issues.

Installation Procedure

The installation process follows a manual binary deployment strategy:

1. Create a dedicated directory, such as C:\GitLab-Runner.
2. Download the appropriate binary for the architecture (x86 64-bit, ARM 64-bit, or x86 32-bit).
3. Rename the binary to gitlab-runner.exe.
4. Apply strict Write permission restrictions to the directory and the executable to prevent unauthorized users from replacing the binary and executing code with elevated privileges.
5. Open an elevated command prompt.
6. Install and start the runner as a service.

Service Configuration and Logon Failures

The runner can be installed using the Built-in System Account or a specific user account. When using a user account, a common failure occurs during the gitlab-runner start command:

FATA[0000] Failed to start GitLab Runner: The service did not start due to a logon failure.

This error typically stems from the user account lacking the SeServiceLogonRight permission, which is required for a user to be logged on as a service.

The installation commands generally follow this pattern:

powershell gitlab-runner install --password WINDOWS_MACHINE_PASSWORD gitlab-runner start

GUI Testing and Interactive Desktop Sessions

One of the most significant challenges in Windows CI is the execution of GUI tests (e.g., Ranorex or other desktop automation frameworks). These tools require an interactive user session with access to a visible desktop, which is fundamentally incompatible with standard service-based execution.

The Service Limitation

When GitLab Runner is installed as a Windows service, it executes jobs in a non-interactive session (Session 0). Because this session has no access to the visible desktop, any attempt to launch a GUI application will result in the job hanging or failing immediately.

Solving for GUI Automation

To overcome this limitation, the following architectural shift is required:

• The shell executor must be used. Docker and Kubernetes executors on Windows cannot provide the necessary interactive desktop session.
• The administrator must sign in to Windows with the specific user account intended for the interactive session.
• The GitLab Runner must be started as a foreground process rather than a service.

The command to initiate the runner in the foreground is:

powershell cd C:\GitLab-Runner .\gitlab-runner.exe run

The user session must remain active for the duration of the GUI tests. To ensure these specific jobs are routed to the interactive runner, specific tags must be used in the .gitlab-ci.yml file:

yaml gui_tests: stage: test tags: - windows-gui script: - .\run-gui-tests.ps1

It is important to note that autoscaled or ephemeral Windows runners cannot support GUI tests because they are provisioned as fresh VMs with no logged-in user, thus lacking a visible desktop.

Advanced Troubleshooting and Environment Management

Windows environments introduce specific technical hurdles related to file systems, terminal emulation, and security.

Addressing PathTooLongException

A frequent issue in Windows CI, particularly when using npm, is the PathTooLongException. This occurs when the directory structure generated by the build tool exceeds the legacy Windows limit of 260 characters. This requires either enabling "Long Paths" in the Windows Registry or restructuring the project directory to be shallower.

ANSI Color Code Handling

GitLab Runner pipes output from the build directly to the web interface, supporting ANSI color codes. However, older versions of the Windows command prompt (pre-Windows 10 version 1511) do not natively support these codes and rely on win32 (ANSI.SYS) calls.

When using cross-platform libraries like Colorama that convert ANSI codes to win32 calls, this conversion must be disabled for CI builds. If the conversion occurs, the GitLab web interface will display raw win32 calls instead of the intended colors, as the web interface expects standard ANSI codes.

Security Implications of the Shell Executor

Using the shell executor, especially on a long-lived local server, presents security risks. In this mode, the CI script defined in .gitlab-ci.yml executes commands directly on the host machine without isolation. This means a compromised or malicious pipeline script could potentially access any part of the host system that the runner user has permissions to reach.

While this is often acceptable for solo developers or trusted internal teams, it is a critical vulnerability in multi-tenant environments. The alternative is moving toward containerized builds, though this removes the ability to perform interactive GUI testing.

Comparison of Windows Execution Methods

The choice between hosted and self-managed runners depends on the specific needs of the project, particularly regarding GUI access and resource control.

Conclusion

Implementing GitLab CI on Windows requires a nuanced understanding of the environment's operational constraints. The hosted runners provide an accessible entry point for standard build and test cycles, utilizing Windows 2022 and PowerShell to deliver a managed experience. However, the inherent limitations of non-interactive sessions in both hosted and service-based runners create a significant barrier for GUI automation.

The resolution for GUI testing necessitates a shift toward foreground process execution and the shell executor, sacrificing some of the convenience of service-based automation for the necessity of a visible desktop. Furthermore, the technical challenges of path length limitations and ANSI color rendering highlight the friction between legacy Windows architecture and modern CI/CD requirements. For developers, the path forward involves a strategic choice: leveraging the simplicity of saas-windows-medium-amd64 for headless builds or investing in a dedicated, interactive Windows host for full-spectrum desktop testing. The evolution toward Windows Server 2025 and the continued refinement of Windows containers suggest a move toward better isolation and scalability, yet the fundamental requirement for interactive sessions in GUI testing remains a cornerstone of Windows automation strategy.

Sources

1. Hosted runners on Windows | GitLab Docs
2. Install GitLab Runner on Windows | GitLab Docs
3. Using GitLab.com hosted Windows runners 2025 | GitLab Forum
4. Windows CI Docker | aixxe.net