GitLab Runner Tags – Complete Guide for Complex Scenarios

Written by Bits Lovers on 08 Oct 2021

GitLab Runner Tags – Complete Guide for Complex Scenarios

Article updated on April 2026.

What are GitLab Runner Tags?

Tags are labels you assign to a runner so you can identify it and control which jobs it picks up. If you have more than one runner registered (which is common), tags are how you tell GitLab CI which runner should handle which job.

Why do you need tags?

A GitLab Runner is a separate application that executes CI/CD jobs. You can install it on different operating systems, cloud instances, or virtual machines. Since different projects have different requirements (OS, hardware, cloud account), you need a way to route jobs to the right runner. That is what tags do.

Multiple runners for different AWS accounts

If you deploy runners on AWS EC2 instances, you probably have separate AWS accounts for Dev, QA, and Production. Each account needs its own runner, and each runner should only have permissions for its own account. Tags let you make sure a production deploy job only runs on the production runner, and a dev job only runs on the dev runner.

This matters because deploy scripts often have broad access to your AWS resources. Without tags, you risk a CI job in one environment accidentally hitting resources in another.

When to use tags

Heavy pipelines vs. lightweight projects

Some pipelines need a lot of CPU or memory. It is a good idea to keep those on dedicated runners rather than sharing with smaller projects. If a heavy build hogs a shared runner, everyone else waits.

We covered this in our post about configuring a Runner using AWS Fargate, where we used Fargate for heavy pipelines and a regular runner for everything else. Fargate takes a couple of minutes to spin up an executor, so it is a poor fit for quick jobs that finish in under two minutes. Tags let you route each pipeline to the right infrastructure.

A runner can have multiple tags, or none at all

Tags are optional. You can assign zero tags, one tag, or several tags to a single runner. A runner with no tags can pick up untagged jobs (depending on its run_untagged setting).

Who can configure tags?

Only GitLab administrators can assign tags to shared runners. Project maintainers can configure tags on project-specific runners.

How to configure GitLab Runner Tags

There are two ways to set up tags: during runner creation (the recommended approach), or later through the GitLab admin UI.

Creating a runner with tags (current method)

GitLab introduced a new runner creation workflow starting in version 15.10. The old --registration-token method is deprecated and scheduled for removal in GitLab 20.0. Here is how it works now.

First, create the runner in the GitLab UI:

Go to Settings > CI/CD > Runners
Click New runner
Choose the platform, add your tags, and set the run_untagged option
Click Create runner and copy the authentication token (it starts with glrt-)

Then register it on your machine:

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --token "glrt-xxxxx-YOUR-AUTH-TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest

Notice that the new method uses --token with an authentication token. Tags are set in the UI when you create the runner, not on the command line.

The legacy method (deprecated)

For reference, here is the old approach. This still works on older GitLab versions but will stop working in a future release:

sudo gitlab-runner register \
  --url "https://gitlab.example.com/" \
  --registration-token "THE_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false"

The --tag-list parameter let you specify tags at registration time. The --run-untagged flag controlled whether the runner would pick up jobs that did not specify any tag. If you set --run-untagged="false", the runner only picked up jobs that explicitly matched its tags.

If you are still using --registration-token, migrate to the new workflow as soon as possible. The old registration tokens are long-lived shared secrets, which is a security risk. The new tokens are unique per runner and can be revoked individually.

Editing tags in the GitLab UI

You can also change tags after a runner is created. Navigate to the Settings > CI/CD > Runners section, select your runner, and edit the configuration:

Gitlab Runner Tags

How to use tags in your pipeline

Run jobs on different platforms

If you have a Windows runner tagged windows and a macOS runner tagged macos, you can target each one:

windows_job:
  stage: build
  tags:
    - windows
  script:
    - echo "Running on Windows"

macos_job:
  stage: build
  tags:
    - macos
  script:
    - echo "Running on macOS"

Or if you have a Fargate runner tagged aws-fargate:

build:
  stage: build
  tags:
    - aws-fargate
  script:
    - ./configure && make && make install

Use variables for dynamic tag selection

You can also use CI/CD variables instead of hardcoding tag values:

variables:
  TAG_RUNNER: "aws-fargate"

job:
  tags:
    - linux-large
    - $TAG_RUNNER
  script:
    - echo "Building the project"

This is handy when you want to change the target runner based on the branch or some other condition. You can set TAG_RUNNER in the GitLab UI under Settings > CI/CD > Variables, or override it per pipeline.

Wrapping up

Tags give you control over how jobs get routed to runners. They are essential when you have multiple runners across different environments, operating systems, or cloud accounts. If you are running anything beyond a single shared runner, you will need them.