Gitlab Runner Tags

GitLab Runner Tags – Complete Guide for Complex Scenarios

Article Updated on September 2022.

The GitLab version used for this post: is 13.9.4 

Gitlab Runner Tags it’s our topic today. We will learn how to get all advantages of those features available on GitLab.

What is GitLab Runner Tags?

We can assign the tags to a Runner to classify it or give it an alias to identify the Runner on Gitlab. Because you may have noticed that we can have multiple Runner register on Gitlab.

What kind of problem can the Tags resolve for us?

GitLab Runner is an application that operates with GitLab CI/CD to run jobs in a pipeline. And this application, “Runner,” could be installed in different operating systems and a computer on the cloud or virtual machine. So, we have that flexibility because it may require another operating system depending o which application we try to develop. So, for that reason, we may need a mechanism to select the proper Runner to build our application, which is the main goal for Gitlab Runner Tags.

Multiple Runner for different AWS Accounts.

Also, if your Runner is deployed on AWS Cloud on an EC2 instance, for example, and for a big company that holds more than one AWS account, it may require to deploy one Runner for each AWS Account. This approach could resolve many security issues because the deployment scripts may have full access to deploy your application, so we need to control the Runner’s access to our resources correctly.

For instance, you may have one AWS Account for Dev, QA, and Production environment, and which Runner only has permission to deploy on your account.

So, in that scenario, we must use Gitlab Runner Tags to securely select the proper Runner to perform our deployment or build process.

Isolate Projects Building Process

Which scenarios do we need to use tags?

Sometimes we may have different pipelines that require more resources like CPU, Memory to execute the pipeline. It’s an excellent approach to separate the heavy pipelines from the small projects. To avoid overloading the Runner and causing a bad experience for developers.

That approach was used in our example in our previous blog post, where we configured a Runner using AWS Fargate to build heavy pipelines. And because the AWS Fargate is not a good solution for small projects (due to the time to create an Executor), that takes less than 2 minutes to be executed. So the better choice it’s to make our project directly call the Runner from Fargate and leave the regular Runner for all other projects as default, using the proper Tags.

One Runner can have multiple tags or no tags at all.

It’s worth remembering that Gitlab Runner Tag is an optional configuration. At the same time, we can assign multiple Tags for one specific Runner.

Who can configure the Tags?

Only Administrators can assign Tags to the Runners.

How to configure Gitlab Runner Tags?

We have two approaches to configuring a new Tag on the Runner.

For the first one, we can assign tags to the Runner registration process. And the second way will be in the Administration section on the Web Interface.

Let’s see more details about both approaches.

Creating Gitlab Runner Tags on the Registration Process

sudo gitlab-runner register \ 
	--url "" \ 
    --registration-token "THE_REGISTRATION_TOKEN" \ 
    --executor "docker" \ 
    --docker-image alpine:latest \ 
    --description "docker-runner" \ 
    --tag-list "docker,aws" \ 
    --run-untagged="true" \ 

The parameter —tag-list, it’s one that we can specify what the tags that we would like to assign to the Runner are. Also, there is another crucial parameter: —run-untagged. If you enable that option, the Runner will only pick up projects explicitly using the Runner’s tags.

If you do not enable that option, this Runner will be configured as “Shared Runner,” so Gitlab will share the Runner for any project that doesn’t specify a Tag.

Assigning Gitlab Runner Tags to the Administration area

To assign Tags to the Gitlab Runner, you need to navigate to the Administration area, and select your Runner and then edit the configuration, like the screenshot above:

Gitlab Runner Tags
Gitlab Runner Tags

on the Tags fields, you can type more than one Tag, separate by a comma.

How to use Gitlab Runner Tags

Use tags to run jobs on different platforms.

You can utilize tags to run several jobs on different platforms. For instance, if you own an OS X runner with a tag osx and, or a Windows runner with a tag windows, you can execute a job on a specific platform:

    - build
    - windows-10
    - echo "Hi, welcome to, %USERNAME%!"
    - build
    - macosx
    - echo "Hi, welcome to"

Or if you have a Fargate Runner configured with the “aws-fargate” tag:

    - build
    - aws-fargate
    - echo "" && ./configure && make && make install

Select the Runner dynamically by Tag

Also, it’s possible to make our pipeline even more dynamic by applying variables instead of hardcoding the values. Like the example below:

TAG_RUNNER: aws-fargate
      - linux-large
      - $TAG_RUNNER
      - echo "Let's build our project!"

So, we can manipulate the $TAG_RUNNER value using scripts and then dynamically select the Runner we need.


Gitlab Runner Tags provide us the flexibility to manage our Runner, and for the complex environment, they are essential features to keep control over our resources.

I hope that this post was helpful to you. So please leave a comment and follow us on social media and stay tuned for new posts.

Check also other articles related to Gitlab:

How to use the Gitlab CI Variables

Effective Cache Management with Maven Projects on Gitlab.

Pipeline to build Docker in Docker on Gitlab.

Execute Terraform on Gitlab CI.

How to use Gitlab CI: Deploy to elastic beanstalk

3 thoughts on “GitLab Runner Tags – Complete Guide for Complex Scenarios”

  1. – Include the time and date that this post was written/updates.
    – Include the version of Gitlab and Gitlab Runner you are using.

    1. Hey Frankman,

      Thanks for your feedback. I really appreciate it.
      The article was updated.

      The GitLab version is 13.9.4.

      You should be fine with using this feature, the GitLab doesn’t change the Tag approach for years.

  2. Hi, maybe you can answer my question.

    Imagine that you have 2 runners,
    runner1 tags: windows, geforce
    runner2 tags: windows

    And I launch a job with tag windows, is there any preference to select the runner? or it can be runner1 or runner2 randomly?


Leave a Comment

Your email address will not be published. Required fields are marked *

Free PDF with a useful Mind Map that illustrates everything you should know about AWS VPC in a single view.