@@ -196,9 +196,11 @@ If an open merge request becomes unmergeable due to conflict, its author will be
...
@@ -196,9 +196,11 @@ If an open merge request becomes unmergeable due to conflict, its author will be
If a user has also set the merge request to automatically merge once pipeline succeeds,
If a user has also set the merge request to automatically merge once pipeline succeeds,
then that user will also be notified.
then that user will also be notified.
## Email Headers
## Filtering email
Notification emails include headers that provide extra content about the notification received:
Notification email messages include GitLab-specific headers. You can filter the notification emails based on the content of these headers to better manage your notifications. For example, you could filter all emails for a specific project where you are being assigned either a merge request or issue.
The following table lists all GitLab-specific email headers:
@@ -209,23 +211,21 @@ Notification emails include headers that provide extra content about the notific
...
@@ -209,23 +211,21 @@ Notification emails include headers that provide extra content about the notific
| X-GitLab-Discussion-ID | Only in comment emails, the ID of the thread the comment is from |
| X-GitLab-Discussion-ID | Only in comment emails, the ID of the thread the comment is from |
| X-GitLab-Pipeline-Id | Only in pipeline emails, the ID of the pipeline the notification is for |
| X-GitLab-Pipeline-Id | Only in pipeline emails, the ID of the pipeline the notification is for |
| X-GitLab-Reply-Key | A unique token to support reply by email |
| X-GitLab-Reply-Key | A unique token to support reply by email |
| X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc |
| X-GitLab-NotificationReason | The reason for being notified: one of `mentioned`, `assigned`, or `own_activity` |
| List-Id | The path of the project in a RFC 2919 mailing list identifier useful for email organization, for example, with Gmail filters |
| List-Id | The path of the project in a RFC 2919 mailing list identifier useful for email organization, for example, with Gmail filters |
### X-GitLab-NotificationReason
### X-GitLab-NotificationReason
This header holds the reason for the notification to have been sent out,
The `X-GitLab-NotificationReason` header contains the reason for the notification. The value is one of the the following, in order of priority:
where reason can be `mentioned`, `assigned`, `own_activity`, etc.
Only one reason is sent out according to its priority:
-`own_activity`
-`own_activity`
-`assigned`
-`assigned`
-`mentioned`
-`mentioned`
The reason in this header will also be shown in the footer of the notification email. For example an email with the
The reason for the notification is also included in the footer of the notification email. For example an email with the
reason `assigned` will have this sentence in the footer:
reason `assigned` will have this sentence in the footer:
`"You are receiving this email because you have been assigned an item on {configured GitLab hostname}"`
-`You are receiving this email because you have been assigned an item on <configured GitLab hostname>.`
NOTE: **Note:**
NOTE: **Note:**
Only reasons listed above have been implemented so far.
Notification of other events is being considered for inclusion in the `X-GitLab-NotificationReason` header. For details, see this [related issue](https://gitlab.com/gitlab-org/gitlab/issues/20689).
Further implementation is [being discussed](https://gitlab.com/gitlab-org/gitlab/issues/20689).
An issue, epic, or merge request cannot have two scoped labels with the same key.
Every issue, merge request and epic can be assigned any number of labels. The labels are
For example, if an issue is already labeled `priority::3`, and then you apply the
managed in the right sidebar, where you can assign or unassign labels as needed.
`priority::2` label to it, `priority::3` is automatically removed.
This functionality is demonstrated in a video titled [Use scoped labels in GitLab 11.10 for custom fields and custom workflows](https://www.youtube.com/watch?v=4BCBby6du3c).
To assign a label to an issue, merge request or epic:
### 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
Suppose you wanted a custom field in issues to track the platform operating system
that your features target, where each issue should only target one platform. You
would then create labels `platform::iOS`, `platform::Android`, `platform::Linux`,
etc., as necessary. Applying any one of these labels on a given issue would
automatically remove any other existing label that starts with `platform::`.
The same pattern could be applied to represent the workflow states of your teams.
Suppose you have the labels `workflow::development`, `workflow::review`, and
`workflow::deployed`. If an issue already has the label `workflow::development`
applied, and a developer wanted to advance the issue to `workflow::review`, they
would simply apply that label, and the `workflow::development` label would
automatically be removed. This behavior already exists when you move issues
across label lists in an [issue board](issue_board.md#creating-workflows), but
now, team members who may not be working in an issue board directly would still
be able to advance workflow states consistently in issues themselves.
## Creating labels
1. In the label section of the sidebar, click **Edit**, then:
- In the list, click the labels you want. Each label is flagged with a checkmark.
- Find labels by entering a search query and clicking search (**{search}**), then
click on them. You can search repeatedly and add more labels.
1. Click **X** or anywhere outside the label section and the labels are applied.
NOTE: **Note:**
You can also assign a label with the [`/assign @username` quick action](quick_actions.md).
A permission level of Reporter or higher is required to create labels.
### New project label
## Label management
To create a **project label**, navigate to **Issues > Labels** in the project.
Users with a [permission level](../permissions.md) of Reporter or higher are able to create
This page only shows the project labels in this project, and the group labels of the
and edit labels.
project's parent group.
Click the **New label** button. Enter the title, an optional description, and the
### Project labels
background color. Click **Create label** to create the label.
If a project has no labels, you can generate a default set of project labels from
View the project labels list by going to the project and clicking **Issues > Labels**.
its empty label list page:
The list includes all labels that are defined at the project level, as well as all
labels inherited from the parent group. You can filter the list by entering a search
query at the top and clicking search (**{search}**).
- Group labels (including subgroup ancestors and subgroup descendants)
- Project labels
- You can [filter](../search/index.md#issues-and-merge-requests) the group epic list
Suppose you wanted a custom field in issues to track the operating system platform
page by: **(ULTIMATE)**
that your features target, where each issue should only target one platform. You
- Current group labels
would then create three labels `platform::iOS`, `platform::Android`, `platform::Linux`.
- Descendant group labels
Applying any one of these labels on a given issue would automatically remove any other
existing label that starts with `platform::`.
The same pattern could be applied to represent the workflow states of your teams.
Suppose you have the labels `workflow::development`, `workflow::review`, and
`workflow::deployed`. If an issue already has the label `workflow::development`
applied, and a developer wanted to advance the issue to `workflow::review`, they
would simply apply that label, and the `workflow::development` label would
automatically be removed. This behavior already exists when you move issues
across label lists in an [issue board](issue_board.md#creating-workflows), but
now, team members who may not be working in an issue board directly would still
be able to advance workflow states consistently in issues themselves.
### Filtering in issue boards
This functionality is demonstrated in a video regarding
[using scoped labels for custom fields and workflows](https://www.youtube.com/watch?v=4BCBby6du3c).
- From [project boards](issue_board.md), you can use the [search and filter bar](../search/index.md#issue-boards)
### Scoped labels with nested scopes
to filter by:
- Group labels
- Project labels
- From [group issue boards](issue_board.md#group-issue-boards-premium), you can use the
You can create a label with a nested scope by using multiple double colons `::` when creating
[search and filter bar](../search/index.md#issue-boards) to filter by group labels only. **(PREMIUM)**
it. In this case, everything before the last `::` will be the scope.
- From [project boards](issue_board.md), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter),
For example, `workflow::backend::review` and `workflow::backend::development` are valid
you can filter by: **(STARTER)**
scoped labels, but they **can't** exist on the same issue at the same time, as they
- Group labels
both share the same scope, `workflow::backend`.
- Project labels
- From [group issue boards](issue_board.md#group-issue-boards-premium), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter),
Addtionally, `workflow::backend::review` and `workflow::frontend::review` are valid
you can filter by group labels only. **(STARTER)**
scoped labels, and they **can** exist on the same issue at the same time, as they
both have different scopes, `workflow::frontend` and `workflow::backend`.
## Subscribing to labels
## Subscribing to labels
From the project label list page and the group label list page, you can subscribe
From the project label list page and the group label list page, you can click **Subscribe**
to [notifications](../profile/notifications.md) of a given label, to alert you
to the right of any label to enable [notifications](../profile/notifications.md) for that
that the label has been assigned to an epic, issue, or merge request.
label. You will be notified whenever the label is assigned to an epic,
issue, or merge request.
If you are subscribing to a group label from within a project, you can select to subscribe
to label notifications for the project only, or the whole group.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14189) in GitLab 8.9.
>
> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab/issues/14523) considers changing this.
> - Introduced in GitLab 8.9.
> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-foss/issues/18554) considers changing this.
Labels can have relative priorities, which are used in the "Label priority" and
Labels can have relative priorities, which are used in the **Label priority** and
"Priority" sort orders of the epic, issue, and merge request list pages.
**Priority** sort orders of the epic, issue, and merge request list pages. Prioritization
for both group and project labels happens at the project level, and cannot be done
from the group label list.
From the project label list page, star a label to indicate that it has a priority.
From the project label list page, star a label to indicate that it has a priority.
