The deployment of the GitLab Runner on Windows environments represents a critical intersection between continuous integration (CI) orchestration and Windows-native systems administration. At its core, the GitLab Runner is a lightweight, Go-based application distributed as a single binary, designed to execute jobs defined in a GitLab CI/CD pipeline and report the outcomes back to the GitLab instance. This architecture allows for a decoupled execution environment where the runner can reside on a dedicated Windows Server—whether physical, virtual, or a cloud-based instance—while communicating with GitLab.com, a self-managed GitLab instance, or GitLab Dedicated across various service tiers including Free, Premium, and Ultimate.
The operational flow of the runner involves a specific sequence of events: the runner communicates with the GitLab API via a registration token to establish a secure bond, and subsequently, it polls the GitLab instance for pending jobs. Once a job is assigned, the runner utilizes a specific executor—such as the shell executor—to run scripts on the host machine. This capability enables the automation of complex Windows-specific tasks, such as deploying .NET applications, managing Active Directory, or executing legacy PowerShell scripts, providing a bridge between modern DevOps practices and traditional Windows infrastructure.
Foundational Prerequisites for Windows Installation
Before initiating the download or installation process, several environmental requirements must be met to ensure stability and prevent runtime failures.
- Git for Windows: The GitLab Runner relies entirely on Git binaries to clone repositories and manage version control. Since the runner binary does not include Git, it must be installed separately from the official site. Without Git, the runner cannot retrieve the source code required to execute the pipeline.
- User Account Credentials: While the runner can operate under the Built-in System Account, administrators may choose to run it under a specific user account. If this path is chosen, a valid password for that user account is mandatory during the installation process.
- System Locale Configuration: The system locale must be explicitly set to English (United States). This is a critical requirement to avoid character encoding issues that have been documented in issue 38702, which could lead to job failures or corrupted logs.
- Administrative Privileges: All installation and registration commands must be executed within a PowerShell or Command Prompt window launched with elevated (Administrator) privileges.
Binary Acquisition and Directory Setup
The installation process begins with the creation of a dedicated environment for the runner binary. It is recommended to establish a root-level directory to avoid permission complications and long file path issues.
The standard procedure involves creating a folder, such as C:\GitLab-Runner. Once this directory is established, the administrator must download the appropriate binary based on the system architecture. GitLab provides binaries for:
- x86 64-bit (AMD64)
- ARM 64-bit
- x86 32-bit
The binary should be placed within the created folder and, for ease of command execution, renamed to gitlab-runner.exe.
A critical security consideration during this phase is the restriction of write permissions on the C:\GitLab-Runner directory and the executable itself. If write permissions are left open to regular users, a malicious actor could replace the gitlab-runner.exe with a compromised binary, allowing for the execution of arbitrary code with the elevated privileges assigned to the runner service.
Detailed Installation Workflows
Depending on the preferred toolset, the installation can be performed via standard Command Prompt or PowerShell.
Manual Installation via Command Prompt
For those utilizing a standard elevated command prompt, the sequence is as follows:
- Navigate to the directory:
cd C:\GitLab-Runner - Install the service:
.\gitlab-runner.exe install - Start the service:
.\gitlab-runner.exe start
Automated Installation via PowerShell
For a more streamlined approach, PowerShell can be used to automate the folder creation and binary download.
powershell
New-Item -Path 'C:\GitLab-Runner' -ItemType Directory
cd 'C:\GitLab-Runner'
Invoke-WebRequest -Uri "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe" -OutFile "gitlab-runner.exe"
.\gitlab-runner.exe install
.\gitlab-runner.exe start
In scenarios where a specific user account is required instead of the System Account, the installation command is modified to include credentials:
powershell
.\gitlab-runner.exe install --user $user --password $password
.\gitlab-runner.exe start
Runner Registration and Integration
Installing the binary and starting the service is only the first half of the process. The runner must be registered with the GitLab instance to receive jobs. This is achieved by navigating to the GitLab admin portal under Settings -> CI/CD -> Runners and selecting "Show runner installation and registration instructions."
The registration process is initiated by executing:
powershell
.\gitlab-runner.exe register
Alternatively, a non-interactive registration can be performed using a single command containing all necessary tokens and configurations:
powershell
.\gitlab-runner.exe register --url $url --registration-token $regtoken --executor shell --tag-list $tags --name $name -n
The registration requires the following specific parameters:
- GitLab URL: The web address of the GitLab instance.
- Registration Token: A unique token provided by the GitLab instance to authenticate the runner.
- Executor: For Windows, the
shellexecutor is common, which allows the runner to execute commands directly on the host. - Tags: Labels used to ensure jobs are routed to the correct runner (e.g., "windows", "powershell").
- Name: A descriptive name for the runner to identify it within the GitLab UI.
PowerShell Versioning and Shell Configuration
A pivotal decision for Windows administrators is the selection of the PowerShell version for job execution.
PowerShell 7 (pwsh)
PowerShell 7 is the current recommended version because it is cross-platform and provides the latest features. If PowerShell 7 is installed, the GitLab Runner defaults to using pwsh, and no further configuration of the config.toml file is necessary.
PowerShell 5.1 (Windows PowerShell)
In many enterprise environments, administrators must support legacy scripts written for PowerShell 5.1. Because the GitLab Runner defaults to pwsh, a manual override is required in the configuration file.
The configuration file is located at C:\GitLab-Runner\config.toml. To switch to PowerShell 5.1, the line:
shell = "pwsh"
must be changed to:
shell = "powershell"
For those automating this change via script, the following logic is applied:
powershell
$config = Get-Content .\config.toml
$config = $config -replace "shell = ""pwsh""", "shell = ""powershell"""
$config | Set-Content .\config.toml
Operational Capabilities and Advanced Features
The GitLab Runner is designed with high flexibility to handle diverse workload requirements. Its feature set includes:
- Concurrency Management: The ability to run multiple jobs simultaneously and limit the number of concurrent jobs per token.
- Diverse Execution Environments: While this guide focuses on the shell executor, runners can also operate using Docker containers, Docker-SSH, or remote SSH servers.
- Dynamic Configuration: The runner supports automatic configuration reloading, meaning changes to
config.tomlcan take effect without requiring a full service restart. - Monitoring: It includes an embedded Prometheus metrics HTTP server and referee workers to pass job-specific data back to GitLab.
- Persistence: Once installed as a service, the runner automatically starts after system reboots.
Maintenance and Lifecycle Management
Maintaining the runner involves regular updates and the ability to cleanly remove the software when it is no longer needed.
Upgrading the Runner
To upgrade to a newer version of the GitLab Runner, the service must first be stopped:
powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe stop
After stopping the service, the administrator downloads the latest binary for the appropriate architecture (x86 64-bit, ARM 64-bit, or x86 32-bit) and replaces the existing gitlab-runner.exe in the installation folder. Finally, the service is restarted:
powershell
.\gitlab-runner.exe start
Uninstallation Process
To completely remove the GitLab Runner from a Windows system, an elevated command prompt is required to execute the following sequence:
powershell
cd C:\GitLab-Runner
.\gitlab-runner.exe stop
.\gitlab-runner.exe uninstall
cd ..
rmdir /s GitLab-Runner
Troubleshooting and Technical Considerations
Windows environments present specific challenges that may arise during the deployment of the runner.
- Interactive Sessions: It is important to note that Windows services do not provide interactive desktop sessions. Any job that requires a GUI or a logged-in user session will fail if run as a service.
- Account Validation Errors: If the runner encounters an error stating "The account name is invalid" during installation with a specific user, administrators should attempt to add a backslash (
\) to the account name to specify the local or domain context. - Log Access: For debugging purposes, all runner logs are stored within the Windows Event Log.
- Git Dependency: If jobs fail with "git not found" errors, verify that Git for Windows is installed and that the binary path is included in the system's environment variables.
Comparison of Installation Methods
| Method | Tool Used | Complexity | Ideal Use Case |
|---|---|---|---|
| Manual | Command Prompt | Low | Single runner setup |
| Scripted | PowerShell | Medium | Rapid deployment |
| Automated | Custom Function | High | Large scale fleet deployment |
Conclusion
The installation of GitLab Runner on Windows is a structured process that transforms a standard Windows Server into a powerful automation node. By adhering to the strict requirements of English (US) locale settings and ensuring the presence of Git for Windows, administrators can establish a stable environment for CI/CD pipelines. The transition from the default pwsh to powershell 5.1 allows for the integration of legacy script libraries, while the use of the shell executor provides direct access to the Windows operating system. Security is maintained through the strict limitation of write permissions on the binary directory, preventing privilege escalation. Ultimately, the Go-based architecture ensures that the runner remains lightweight and efficient, providing the necessary scalability to handle multiple concurrent jobs across various tiers of the GitLab ecosystem.