GitLab Custom Runner

If you have been using GitLab for a while, you may often hear the term “runners” around but you may not know them very well.

What are runners?

Runners are application that can run scripts with GitLab CI/CD. Say when you finish working on a feature of your app, you would want to test your work every time you add changes to it. With GitLab runner, you could program the runner to start an automated testing every time you push changes to your branch. Also it doesn’t have to be testing, you could run multiple things in it like building and deployment.

To do this, it needs a computer to run it on. GitLab have some public runners that we can use. If your campus have its own GitLab (for me it’s gitlab.cs.ui.ac.id), the campus would have its own runners that usually shared for students and lecturers.

What are custom runners?

Custom runners are runners made by third party individual or groups. It can be registered to be used for the public, or maybe for private use only.

Why custom runners?

Public runners aren’t 100% reliable. It can go down, or have unwanted behaviors. For example in my project, we have finished a feature and we want to push them to our project branch. We have automated testing scripted to run on our GitLab project pipeline. Our test came out fail every time. We tried testing it on our local workstation and it came out success. After further investigation we found that our GitLab runner failed to download a UI library when it tried to test our application webpage. It doesn’t always happen but it happens at a rate that may hinder our work pace. So to solve this we decide to use one of our workstation as a runner for our project, hence a custom runner.

How?

For this tutorial I’m going to install an register a custom gitlab runner on Windows.

1. Create a new folder for your runner.
2. Download the runner for Windows at https://docs.gitlab.com/runner/install/windows.html. Pick 64-bit or 32-bit accordingly. You can rename it however you want but for this tutorial, I will rename it as gitlab-runner-tutorial.exe

3. Go to your project repository on GitLab and open Settings>CI/CD. Under the Runners section, you would found this.

Copy both the URL and registration token to clipboard, we will need them later.

4. Open Windows Powershell as Admin.

5. Register your runner with .\[your-runner.exe] register. For this tutorial it would be .\gitlab-runner-tutorial.exe register.

In this section they would ask you:

a. The gitlab instance URL: paste the URL you copied from your project settings at step 3.

b. Your project registration code: paste the code you copied from step 3.

c. Description: You could add your own description for your runner. For this tutorial I use “Custom Gitlab Runner Tutorial”.

d. Tags: We will come to this later, for now let’s just leave it blank.

e. Executor: You can use multiple executor for your runner, but it is recommended to use docker since it is the most versatile.

f. If you do pick docker, it will ask which image will be use as default. You can pick any image, but for this tutorial I will use ruby:2.6. This image is not used always, it will only be use as default if a job doesn’t describe what image will be used.

After doing this there will be a config.toml file created on your runner folder.

6. Install your runner with .\[your-runner.exe] install, then run it with .\[your-runner.exe] start. For this tutorial it would be .\gitlab-runner-tutorial.exe install and .\gitlab-runner-tutorial.exe start.

After doing this, you would have a service running call gitlab-runner running. You can check it on your task manager on the Service tab.

And when you check your project on the Runners settings, you could see your runner is registered.

Set up your custom runner to pick jobs

Now that you have registered a runner, time to set your runner to pick on jobs. On the runners settings, you can click on the pencil button to edit your runner. If you do you will be greeted with a page like this.

On the tags, you can put your own tags. Tags are usually consist of one word, and are separated from on another by a comma. For example If I want to add frontend and backend tags to this runner, it would look something like this.

After saving those settings, we need to add tags to our jobs for our runner to pick up. To do this add tags on your gitlab-ci.yml.

With this tags, our custom runner would pick job1 and job2 since both jobs have the matching tags as our runner.

If it all went well, the next time you run those jobs, you can see that the runner will be your runners description when you see your job’s pipeline.

Custom runners are cool and all but just remember since it is you own computer running those jobs, so say if you use your personal computer as runner, if your computer is off, any jobs with your runner tags will not run and fail, so keep that in mind.