From 6f2e3a3bd6838c8f6b67187421cf1226f98c6cdb Mon Sep 17 00:00:00 2001
From: Marcel Amirault <4155490-marcel.amirault@users.noreply.gitlab.com>
Date: Fri, 10 Sep 2021 16:06:36 +0000
Subject: [PATCH] Update runner tags reference style
---
doc/ci/caching/index.md | 2 +-
doc/ci/migration/jenkins.md | 4 +--
doc/ci/runners/configure_runners.md | 48 +++++++++++++++++++++++--
doc/ci/yaml/index.md | 54 +++++++++--------------------
4 files changed, 66 insertions(+), 42 deletions(-)
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md
index 009fb13c89531..29a03fe06abbc 100644
--- a/doc/ci/caching/index.md
+++ b/doc/ci/caching/index.md
@@ -45,7 +45,7 @@ can't link to files outside it.
To ensure maximum availability of the cache, do one or more of the following:
-- [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs
+- [Tag your runners](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) and use the tag on jobs
that share the cache.
- [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects).
- [Use a `key`](../yaml/index.md#cachekey) that fits your workflow. For example,
diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md
index 99bdc255f0e20..925dff8751c7b 100644
--- a/doc/ci/migration/jenkins.md
+++ b/doc/ci/migration/jenkins.md
@@ -130,7 +130,7 @@ There are some important differences in the way runners work in comparison to ag
- Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/runners_scope.md).
They self-select jobs from the scopes you've defined automatically.
-- You can also [use tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and
+- You can also [use tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) for finer control, and
associate runners with specific jobs. For example, you can use a tag for jobs that
require dedicated, more powerful, or specific hardware.
- GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html).
@@ -230,7 +230,7 @@ and is meant to be a mapping of concepts there to concepts in GitLab.
The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/index.md)
to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage
of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users).
-We also support using [tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs
+We also support using [tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) to direct different jobs
to different runners (execution agents).
The `agent` section also allows you to define which Docker images should be used for execution, for which we use
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md
index 85c212c9ee1af..13897b934c562 100644
--- a/doc/ci/runners/configure_runners.md
+++ b/doc/ci/runners/configure_runners.md
@@ -169,13 +169,13 @@ project.
-## Use tags to limit the number of jobs using the runner
+## Use tags to control which jobs a runner can run
You must set up a runner to be able to run all the different types of jobs
that it may encounter on the projects it's shared over. This would be
problematic for large amounts of projects, if it weren't for tags.
-GitLab CI tags are not the same as Git tags. GitLab CI tags are associated with runners.
+GitLab CI/CD tags are not the same as Git tags. GitLab CI/CD tags are associated with runners.
Git tags are associated with commits.
By tagging a runner for the types of jobs it can handle, you can make sure
@@ -184,6 +184,8 @@ shared runners will [only run the jobs they are equipped to run](../yaml/index.m
For instance, at GitLab we have runners tagged with `rails` if they contain
the appropriate dependencies to run Rails test suites.
+### Set a runner to run untagged jobs
+
When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick**
[tagged jobs](../yaml/index.md#tags).
To change this, you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project.
@@ -238,6 +240,48 @@ Example 2:
1. A job that has no tags defined is executed and run.
1. A second job that has a `docker` tag defined is stuck.
+### Use tags to run jobs on different platforms
+
+You can use tags to run different jobs on different platforms. For
+example, if you have an OS X runner with tag `osx` and a Windows runner with tag
+`windows`, you can run a job on each platform:
+
+```yaml
+windows job:
+ stage:
+ - build
+ tags:
+ - windows
+ script:
+ - echo Hello, %USERNAME%!
+
+osx job:
+ stage:
+ - build
+ tags:
+ - osx
+ script:
+ - echo "Hello, $USER!"
+```
+
+### Use CI/CD variables in tags
+
+> Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/35742).
+
+You can use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection:
+
+```yaml
+variables:
+ KUBERNETES_RUNNER: kubernetes
+
+ job:
+ tags:
+ - docker
+ - $KUBERNETES_RUNNER
+ script:
+ - echo "Hello runner selector feature"
+```
+
## Configure runner behavior with variables
You can use [CI/CD variables](../variables/index.md) to configure runner Git behavior
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index 4e0c479f999c6..10713f3ae7c0a 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -1830,16 +1830,22 @@ rspec:
> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3.
> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3.
-In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later, the number of tags must be less than `50`.
-
Use `tags` to select a specific runner from the list of all runners that are
available for the project.
When you register a runner, you can specify the runner's tags, for
-example `ruby`, `postgres`, `development`.
+example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must
+be assigned every tag listed in the job.
+
+**Keyword type**: Job keyword. You can use it only as part of a job or in the
+[`default:` section](#custom-default-keyword-values).
+
+**Possible inputs**:
+
+- An array of tag names.
+- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later.
-In the following example, the job is run by a runner that
-has both `ruby` and `postgres` tags defined.
+**Example of `tags`**:
```yaml
job:
@@ -1848,42 +1854,16 @@ job:
- postgres
```
-You can use tags to run different jobs on different platforms. For
-example, if you have an OS X runner with tag `osx` and a Windows runner with tag
-`windows`, you can run a job on each platform:
-
-```yaml
-windows job:
- stage:
- - build
- tags:
- - windows
- script:
- - echo Hello, %USERNAME%!
+In this example, only runners with *both* the `ruby` and `postgres` tags can run the job.
-osx job:
- stage:
- - build
- tags:
- - osx
- script:
- - echo "Hello, $USER!"
-```
+**Additional details**:
-In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35742), you can
-use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection:
+- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later,
+ the number of tags must be less than `50`.
-```yaml
-variables:
- KUBERNETES_RUNNER: kubernetes
+**Related topics**:
- job:
- tags:
- - docker
- - $KUBERNETES_RUNNER
- script:
- - echo "Hello runner selector feature"
-```
+- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run).
### `allow_failure`
--
GitLab