Install and Register GitLab Runner on Windows

In this guide, you will learn how to Install and Register GitLab Runner on Windows. GitLab Runner is an open-source application and it is written in Go. It works with GitLab CI/CD to run jobs in a pipeline. It can be run as a single binary; no language-specific requirements are needed. Please see how to use AWS CodeCommit, Azure DevOps and GitHub integration for Docker and Kubernetes deployment, and how to build your first CI/CD Pipeline in Azure DevOps using ASP.Net Core Application.

You can choose to install the GitLab Runner application on the infrastructure that you own or manage. If you do, you should install GitLab Runner on a machine that’s separate from the one that hosts the GitLab instance for security and performance reasons.

When you use separate machines, you can have different operating systems and tools, like Kubernetes or Docker, on each. You can install GitLab Runner on several different supported operating systems.

Other operating systems may also work, as long as you can compile a Go binary on them. GitLab Runner can also run inside a Docker container or be deployed into a Kubernetes cluster.

Here are some related guides: How to install Git on macOS, How to uninstall Git on macOS, Practical Git use with markdown, how to clone a repository and install software from GitHub on Windows.

Software Development

Some of the tools for software development using continuous methodologies are:

• Continuous Integration (CI)
• Continuous Delivery (CD)
• Continuous Deployment (CD)

GitLab CI is an open-source continuous integration service included with GitLab. GitLab CI/CD can automatically build, test, deploy, and monitor your applications by using Auto DevOps.

Various concepts describe and run your build and deployment and one of which is “GitLab Runner”. First, let’s highlight on the different aspects of GitLab Runner, and then dive into how to Install and Register GitLab Runner on Windows. And also how to start the GitLab runner afterwards.

GitLab Runner officially supported binaries are available for the following architectures as of the time of writing this piece: x86, AMD64, ARM64, ARM, s390x, ppc64le. GitLab Runner officially supports the following operating systems: Linux, Windows, macOS, FreeBSD.

Different types of Runners

There are different types of GitLab runners and they are as follows:

• Shared Runner
• Specific Runner
• Group Runner

Shared Runners are relevant for jobs that have similar requirements, and multiple projects. Rather than having multiple Runners idling for many projects, you can have a single or a small number of Runners that handle multiple projects. This makes it easier to maintain and update them.

Shared Runners process jobs using a fair usage queue. In contrast to specific Runners that use a FIFO queue, this prevents cases where projects create hundreds of jobs which can lead to eating all available shared Runners resources. A Runner that serves all projects is called a shared Runner.

Group Runners are useful when you have multiple projects under one group and would like all projects to have access to a set of Runners. Group Runners process jobs using a FIFO queue.

Install GitLab Runner on Windows

Now, let’s Install and Register GitLab Runner on Windows. To do this, please follow the steps below.

1: Create a folder somewhere in your system, For instance on the C drive. This can be created on any other drive: C:\GitLab-Runner.

2: Download the binary for 64-bit or 32-bit and put it into the folder you created. Upon clicking on the 46-bits, the GitLab runner executable will be downloaded as shown below.

3: Copy the GitLab runner executable that has just been downloaded and paste it in the location that was created. The following assumes you have renamed the binary to GitLab-runner.exe (This step is optional).

Note: 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. You can verify this by following the steps below.

You can right-click on the GitLab Runner directory, click on Properties and then Security. Ensure the regular users do not have the Write Permission assigned.

4: Run an elevated command prompt as shown below

This will ensure the Command Prompt opens as an Administrator as shown below. Navigate to the GitLab-Runner directory

Run service using Built-in System Account: Now, we have to install the GitLab Runner as a service using the command below.

gitlab-runner.exe install

If you wish to run service using user account, please use the command below and substitute your account details appropirately.

gitlab-runner.exe install --user ENTER-YOUR-USERNAME --password ENTER-YOUR-PASSWORD

Note: When you run .\gitlab-runner.exe install it installs gitlab-runner as a Windows service. You can find the logs in the Event Viewer with the provider name gitlab-runner. You can also view this from PowerShell using the command below.

Get-WinEvent -ProviderName gitlab-runner

View the version of GitLab- Runner Installed

To view the version of the installed GitLab Runner, run the command as shown in the image below. As you can see, it will display the version, OS/Architecture etc.

Start the GitLab Runner Service: To do this, use the command below. From the image below, the installed GitLab-Runner is already running.

gitlab-runner.exe start

Register GitLab Runner

Now that we have installed GitLab Runner, we have to register the GitLab Runner on Windows. Registering a runner is the process that binds the runner with one or more GitLab instances.

After you install the application, you register individual runners, or multiple runners on the same host machine, each with a different configuration, by repeating the register command. Runners are the agents that run the CI/CD jobs that come from GitLab.

When you register a runner, you are setting up communication between your GitLab instance and the machine where GitLab Runner is installed.

• Runners usually process jobs on the same machine where you installed GitLab Runner. However, you can also have a runner process jobs in a container, in a Kubernetes cluster, or in auto-scaled instances in the cloud.

Before registering a runner, you need the following parameters:

• Install it on a server separate from where GitLab is installed. (This we have done in the steps above).
• Obtain a token (These steps will be expanded more later as we progress):
  • For a shared runner, have an administrator go to the GitLab Admin Area and click Overview > Runners
  • For a group runner, go to Settings > CI/CD and expand the Runners section
  • For a project-specific runner, go to Settings > CI/CD and expand the Runners section

Shared Runners are enabled by default as of GitLab 8.2, but can be disabled with the Disable shared Runners button which is present under each project’s Settings ➔ CI/CD page.

Run the command below to Register GitLab-Runner

gitlab-runner.exe register

Next, you will be required to enter your GitLab instance URL (also known as the gitlab-ci coordinator URL) as shown below

Setting up a specific GitLab-Runner

Enter the token you obtained to register the runner. To get your Token, you will need to access your GitLab project as discussed above

Navigate to the following section “Runners” and Expand it as shown below

As you can see, we now have access to the registration token as shown below

Enter the Registration Token and also enter a description for the runner. You can change this value later in the GitLab user interface.

Enter the tags associated with the runner, separated by commas. You can change this value later in the GitLab user interface.

Please enter the Runner executor such as: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: docker. I will be using Shell as shown below.

Now you have successfully installed and registered GitLab runner as shown in the figure above. If your GitLab registration fails, you may want to see this related guide “Panic: Failed to register the GitLab-runner, you may be having network issues“.

Note: If you entered docker as your executor, you’ll be asked for the default image to be used for projects that do not define one in .gitlab-ci.yml. You can enter alpine:latest

Please enter the default Docker image (e.g. ruby:2.1):
alpine:latest

You can see the GitLab Runner configuration in the config.toml file under the GitLab-Runner folder as shown below.

GitLab Runner implements a number of executors that can be used to run your builds in different scenarios.

The executors support different platforms and methodologies for building a project. The table below shows the key facts for each executor which will help you decide which executor to use.

Shell executor: The Shell is the simplest executor to configure. All required dependencies for your builds need to be installed manually on the same machine that GitLab Runner is installed on.

Check if the Runner is activated for the Project

Basically, you will have to follow the same steps as discussed previously. Click on the GitLab project and navigate to Settings > CI/CD and expand the Runners section.

As you can see below, the runner is activated for this project

Nicely done, congratulations. You have successfully followed each and every step needed to Install and Register GitLab Runner on Windows. I hope you found this blog post helpful. If you have any questions, please let me know in the comment session.