GitLab Pipeline Tags

• Introduction
  • Use Cases
• Steps
  • Applying Tags To Runners
  • Pipeline Configuration
• References

Introduction

GitLab runners support the use of tags in order to restrict which runners a job can be executed on. This tutorial will show you how to configure your runners and pipelines to make use of this tags feature.

These "tags" are not to be confused with git tags, which are not related to this in any way. It is just unfrotunate that the same term is used for two different things.

Use Cases

A common use case for this is to have your runners on different networks that might have different security restrictions. E.g. I have a runner behind my home NAT, whose servers are not accessable from the internet, but which the runner can access and deploy to. I then have another runner on my Hetzner server, which is able to push/pull images to/from the internet at a much faster speed, which is great when Docker images are sometimes more than 500MB in size and they need deploying on an internet server.

Another reason may be that you have your runners configured differently. I only run generic docker-based runners, but others may have manually setup and configured their runners and have manually installed certain libraries that the runner may need access to.

Steps

Applying Tags To Runners

Navigate to the admin area for your runners, which is at the path: /admin/runners on your domain. So for example:

https://gitlab.mydomain.com/admin/runners

Then click on the pencil icon beside the runner you wish to apply tags to:

That will bring up the following form to edit the runner.

1. Input a comma-separated list of tags into the first form field.
2. Tick the checkbox if you also wish this runner to run untagged jobs (2). I generally don't, and make sure everything is tagged appropriately.
3. Click save.

You should now see the tags listed as little blue pills for your runner.

Pipeline Configuration

Now in your codebase, edit the .gitlab-ci.yml file (1) to add the tags (2) to the jobs that you want to run on specific runners like so:

The tags are just a list, so YAML will be more than happy to use the following alternative format: tags: [tag1,tag2,tag3]

Be Careful When Specifying Multiple Tags

You can specify multiple tags in the pipeline file. However, you need to remember that this will mean that the job can only run on a runner that has all the tags specified, not just some/any of them.

References

• GitLab Docs - GitLab Runner