GitLab Runner with Docker Compose in Windows
What is a GitLab Runner?
A GitLab runner [1] is an application responsible of the creation and handling of CI/CD jobs of GitLab pipelines. It can be installed on Linux, macOS, FreeBSD and Windows.
As you know, we can use tags in your pipeline to select the runner that you want. So, you could have multiple runners, each one with a different configuration.
Usually companies have their own runners and for personal small projects we can use the shared runners provided by GitLab (every account has a limit of minutes per month).
The current setup is a non-enterprise project, the developer machine is a Windows 10 and we need jobs with Linux or Windows images. This setup is common when we’re maintaining .NET-Framework applications (Windows containers) and we’re developing .NET-Core, .NET-Standard, .NET5, .NET6, and Java applications (Linux containers).
What is Docker Compose?
Docker Compose [2] is a container orchestrator, so we can easily configure a docker container with a manifest file (compose.yaml).
Docker Compose is installed with Docker Desktop so you just need to install it from docker.com. Beware of the service agreement, it has changed.
Configuring Docker Desktop
First of all, I’d recommend install and configure WSL 2 [3] in your Windows 10 machine. How to do it is out of the scope of this story.
You have to download and install Docker Desktop. Or just run the following command.
After installing it, you should see the whale icon and you can open the dashboard.
If you need a Windows container, then you should switch to Windows containers mode. In this story I’m going to explain how to do it with Linux containers.
Configuring our runner
1 We should create a folder (e.g. my-project-runner) for our runner.
2 Copy the following manifest file (compose.yaml) in the runner folder.
The configuration file for the runner will be stored in the folder named config (e.g. c:\my-project-runner\config).
3 Copy the following installation PowerShell script in the runner folder.
Warning: Docker Desktop should be running in background, otherwise all docker commands will fail.
4 For the next steps we need some information. In GitLab, go to your project and then in left menu: Settings > CI/CD > Runners > Specific runners
It should be in the a URL similar to:
We have to note the following information:
- GitLab instance URL (https://gitlab.com/).
- The registration token.
5 Register the runner for our project (or group). Execute the previous script. It will start the container called gitlab-runner and it will execute the command register inside the container.
6 The GitLab instance URL is requested so we should fill it up.
7 The registration token of your project is requested (copy it from the web and paste it in the your terminal).
8 A description is requested. You can leave it empty or you can set a name for it (e.g. helloworld6-runner-1).
9 The tags to identify you runner. In my case I’ve used linux and docker, but you can use whatever you want (it should be in tags section in your .gitlab-ci file).
10 An optional maintenance note can be added. You can leave it empty.
11 The executor is requested, it has to be docker.
12 The default image is requested (you can change it in your jobs in the section image), in my case it will be one of the lightest, alpine:latest.
13 Now the runner is registered and it is ready to be used (it is taken automatically based on the tags).
The new runner is visible is your Docker Desktop dashboard and the jobs appears during their execution.
We can see in the log of the job that the runner is our runner instead of a shared runner.
Stop our runner
1 If we want to stop the runner locally we can call to the docker compose command. Don’t forget starting it later.
2 Or we could close Docker Desktop, so it won’t be available.
3 Or we can pause it in the specific runner section (there is a pause symbol button).
Remove our runner
When we don’t our runner anymore, we can remove it.
1In GitLab, in available specific runners clicking on the red button “Remove runner”.
2 Remove it locally calling to the following command.
Conclusions
The pipelines are a key point of the quality of any project and we need to spend some resources to run them.
We’ve seen how to easily install and configure a GitLab runner locally. Henceforth, now we don’t have excuses to prepare our pipelines for our personal projects.
References
[1]: GitLab. Run GitLab Runner in a container. Retrieved from https://docs.gitlab.com/runner/install/docker.html
[2]: Docker Documentation. Overview of Docker Compose. Retrieved from https://docs.docker.com/compose/install/
[3]: Microsoft Docs. Install WSL. Retrieved from https://docs.microsoft.com/en-us/windows/wsl/install
This story (it isn’t a paper) provided by Pablo Caballero on Medium is for general information purposes only. All information has been provided in good faith, however I make no representation or warranty of any kind, express or implied, regarding the accuracy, adequacy, validity, reliability, availability or completeness of any information on this story.
