Merge branch 'docs-scoped-label-key' into 'master'

Add a note about nested scopes matching

See merge request gitlab-org/gitlab-ce!28466

1 files changed, 8 insertions, 0 deletions

diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md
index 8e9e9aa79cf..e5f62a3bb8d 100644
--- a/doc/user/project/labels.md
+++ b/doc/user/project/labels.md
@@ -32,6 +32,14 @@ An issue, epic, or merge request cannot have two scoped labels with the same key
 For example, if an issue is already labeled `priority::3` and you apply the label `priority::2` to it,
 `priority::3` is automatically removed.
 
+### Labels with multiple colon pairs
+
+If labels have multiple instances of `::`, the longest path from left to right, until the last `::`, is considered the "key" or the "scope".
+
+For example, `nested::key1::value1` and `nested::key1::value2` cannot both exist on the same issue. Adding the latter label will automatically remove the former due to the shared scope of `nested::key1`.
+
+`nested::key1::value1` and `nested::key2::value1` can both exist on the same issue, as these are considered to use two different label scopes, `nested::key1` and `nested::key2`.
+
 ### Workflows with scoped labels **[PREMIUM]**
 
 Suppose you wanted a custom field in issues to track the platform operating system