@@ -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,
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
| 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-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 |
### X-GitLab-NotificationReason
This header holds the reason for the notification to have been sent out,
where reason can be `mentioned`, `assigned`, `own_activity`, etc.
Only one reason is sent out according to its priority:
The `X-GitLab-NotificationReason` header contains the reason for the notification. The value is one of the the following, in order of priority:
-`own_activity`
-`assigned`
-`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:
`"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:**
Only reasons listed above have been implemented so far.
Further implementation is [being discussed](https://gitlab.com/gitlab-org/gitlab/issues/20689).
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).
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 then you apply the
`priority::2` label to it, `priority::3` is automatically removed.
Every issue, merge request and epic can be assigned any number of labels. The labels are
managed in the right sidebar, where you can assign or unassign labels as needed.
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).
### 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.
To assign a label to an issue, merge request or epic:
## 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:**
A permission level of Reporter or higher is required to create labels.
You can also assign a label with the [`/assign @username` quick action](quick_actions.md).
### New project label
## Label management
To create a **project label**, navigate to **Issues > Labels** in the project.
This page only shows the project labels in this project, and the group labels of the
project's parent group.
Users with a [permission level](../permissions.md) of Reporter or higher are able to create
and edit labels.
Click the **New label** button. Enter the title, an optional description, and the
background color. Click **Create label** to create the label.
### Project labels
If a project has no labels, you can generate a default set of project labels from
its empty label list page:
View the project labels list by going to the project and clicking **Issues > Labels**.
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
### Workflows with scoped labels
- You can [filter](../search/index.md#issues-and-merge-requests) the group epic list
page by: **(ULTIMATE)**
- Current group labels
- Descendant group labels
Suppose you wanted a custom field in issues to track the operating system platform
that your features target, where each issue should only target one platform. You
would then create three labels `platform::iOS`, `platform::Android`, `platform::Linux`.
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)
to filter by:
- Group labels
- Project labels
### Scoped labels with nested scopes
- From [group issue boards](issue_board.md#group-issue-boards-premium), you can use the
[search and filter bar](../search/index.md#issue-boards) to filter by group labels only. **(PREMIUM)**
You can create a label with a nested scope by using multiple double colons `::` when creating
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),
you can filter by: **(STARTER)**
- Group labels
- Project labels
For example, `workflow::backend::review` and `workflow::backend::development` are valid
scoped labels, but they **can't** exist on the same issue at the same time, as they
both share the same scope, `workflow::backend`.
- From [group issue boards](issue_board.md#group-issue-boards-premium), in the [issue board configuration](issue_board.md#configurable-issue-boards-starter),
you can filter by group labels only. **(STARTER)**
Addtionally, `workflow::backend::review` and `workflow::frontend::review` are valid
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
From the project label list page and the group label list page, you can subscribe
to [notifications](../profile/notifications.md) of a given label, to alert you
that the label has been assigned to an epic, issue, or merge request.
From the project label list page and the group label list page, you can click **Subscribe**
to the right of any label to enable [notifications](../profile/notifications.md) for that
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.
> - Priority sorting is based on the highest priority label only. [This discussion](https://gitlab.com/gitlab-org/gitlab-foss/issues/18554) considers changing this.
> - [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.
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.
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. 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.
