GitLab Runner on AWS Windows EC2 Instances

Sourav Biswas

4 min readOct 5, 2021

Prerequisites :

EC2 instance using latest Windows Server-2019 AMI.
Git is installed.
A password for your user account, if you want to run it under your user account rather than the Built-in System Account.
Microsoft Docker Provider (PowerShell as administrator):

Ensure Hyper-V is enabled

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Install all Hyper-V tools

Install-WindowsFeature RSAT-hyper-V-tools -IncludeAllSubFeature

Install the Microsoft Docker Provider

Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
Install-Module -Name DockerMsftProvider -Repository PSGallery -Force

Install Docker

Install-Package -Name docker -ProviderName DockerMsftProvider

Restart Server to ensure Docker service is running

Restart-Computer -Force

Installation Steps:

Create a folder , example — C:\GitLab-Runner.
Download the binary for 64-bit or 32-bit and put it into the folder you created. The following assumes you have renamed the binary to gitlab-runner.exe (optional).
Make sure to restrict the Write permissions on the GitLab Runner directory and executable. If you do not set these permissions, regular users can replace the executable with their own and run arbitrary code with elevated privileges.

Register Runner:

Run the following command to register and install GitLab Windows runner. We need to run the commands from elevated command prompt :

Register GitLab Runner

.\gitlab-runner.exe register

Install GitLab Runner

.\gitlab-runner.exe install

Start GitLab Runner Service

.\gitlab-runner.exe start

Once the commands are executed, check GitLab Repo → Settings → CI/CD → Runners section and verify the runner is added and showing Online status.
Execute the Pipeline with matching tag and make sure the runner is getting picked and pipeline is successful .

Configuration for Concurrent execution:

After registration is completed we need to update `config.toml` file for concurrent execution. We need to change the `concurrent` value based on requirement.

concurrent = 5
check_interval = 0

Restart the runner service and verify service is up with following commands:

Configuration

.\gitlab-runner.exe stop
.\gitlab-runner.exe start
.\gitlab-runner.exe verify

Go to the repo and run the pipeline concurrently number of times and it should run concurrent pipeline till the concurrent value is hit.

Limitations:

Windows GitLab runner don’t support Autoscaling as of now. We can achieve concurrency for executor using config.toml but autoscaling Windows gitlab runner is not possible yet.
GitLab Runner only supports the following versions of Windows which follows Microsoft’s support lifecycle for Windows:

Windows Server 20H2.
Windows Server 2004.
Windows Server 1809.

Linux container is not supported as executor on EC2 Windows runner. We need bare-metal Windows for this to work.
Docker Desktop is not supported on Windows EC2 runner as it requires hardware support for Hyper-V Nested Virtualization. We need bare-metal Windows for this to work.
Only Microsoft supported official Windows images can be used as Executor. Unsupported Windows image can not be used.

Windows Server
Windows Nanoserver
Windows Server Core

Docker-in-docker is not supported.
Gitlab runner installation must use 'C:' as installation drive letter. Other drive letters are not supported yet.

Other Important GitLab Runner Commands:

Stop GitLab Runner Service

.\gitlab-runner.exe stop

Uninstall GitLab Runner

.\gitlab-runner.exe uninstall

Get GitLab Runner Logs

Get-WinEvent -ProviderName gitlab-runner

Troubleshooting :

Issue: Fail to Pull image
Cause: The image is not supported for Windows Docker
Resolution: Use Microsoft supported image as executor.

Issue: Runner showing offline / not connected in GitLab Repo CI/CD settings
Cause: GitLab runner service is stopped or it is uninstalled
Resolution: Start GitLab runner service using .\gitlab-runner.exe start command or install using .\gitlab-runner.exe install command and then start the service. Verify service is up.

Issue: GitLab pipeline is stuck
Cause: No runner with matching tag found
Resolution: Check GitLab runner section and update tag as required.

Issue: Failed to Pull image , not enough space available.
Cause: Less space available on disk
Resolution: Increase disk size or remove unwanted files to free up some spaces.