issue_data_and_actions.md 10.2 KB
Newer Older
Mike Lewis's avatar
Mike Lewis committed
1
# Issue Data and Actions
Marcia Ramos's avatar
Marcia Ramos committed
2 3 4

Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.

Mike Lewis's avatar
Mike Lewis committed
5
## Parts of an Issue
Marcia Ramos's avatar
Marcia Ramos committed
6

7 8 9
The image below illustrates what an issue may look like. Note that certain parts will
look slightly different or will be absent, depending on the version of GitLab being used
and the permissions of the user viewing the issue.
Marcia Ramos's avatar
Marcia Ramos committed
10

11
![Issue view](img/issues_main_view_numbered.png)
Marcia Ramos's avatar
Marcia Ramos committed
12

13
You can find all the information for that issue on one screen.
Marcia Ramos's avatar
Marcia Ramos committed
14 15 16 17

### Issue screen

An issue starts with its status (open or closed), followed by its author,
18
and includes many other functionalities, numbered in the image above to
Marcia Ramos's avatar
Marcia Ramos committed
19 20
explain what they mean, one by one.

21 22 23
Many of the elements of the issue screen refresh automatically, such as the title and
description, when they are changed by another user. Comments and system notes also
update automatically in response to various actions and content updates.
Victor Wu's avatar
Victor Wu committed
24

25
#### 1. New Issue, close issue (reopen issue, report issue)
Marcia Ramos's avatar
Marcia Ramos committed
26

27 28 29 30 31 32 33 34 35 36 37 38 39 40
Clicking on **New issue** will open a new window to create a new issue in the same project.
Clicking on **Close issue** will close this issue, but it will not be deleted. If the
issue is already closed, you can still access it and the button will show **Reopen issue**, as shown below,
which you can click to reopen the issue. A reopened issue is no different from any
other issue.

![Reopen Issue](img/reopen-issue.png)

If you do not have rights to modify the issue, the **close issue** button will be
replaced with **report issue**, which you can click to [submit an abuse report](../../abuse_reports.md)
about the issue. It will also appear if you have rights to modify the issue, but only
after it is closed.

![Report Abuse](img/report-abuse.png)
Marcia Ramos's avatar
Marcia Ramos committed
41 42 43

#### 2. Todos

44 45 46
You can click **add todo** to add the issue to your [GitLab Todo](../../../workflow/todos.md)
list. If it is already on your todo list, the buttom will show **mark todo as done**,
which you can click to mark that issue as done (which will be reflected in the Todo list).
Marcia Ramos's avatar
Marcia Ramos committed
47 48 49

#### 3. Assignee

50 51 52 53
An issue can be assigned to yourself, another person, or [many people](#31-multiple-assignees-STARTER).
The assignee(s) can be changed as much as needed. The idea is that the assignees are
responsible for that issue until it's reassigned to someone else to take it from there.
When assigned to someone, it will appear in their assigned issues list.
Marcia Ramos's avatar
Marcia Ramos committed
54

55 56
TIP: **Tip:**
If a user is not member of that project, it can only be
Marcia Ramos's avatar
Marcia Ramos committed
57 58
assigned to them if they created the issue themselves.

59
##### 3.1. Multiple Assignees **[STARTER]**
60

61 62
Often multiple people work on the same issue together, which can be especially difficult
to track in large teams where there is shared ownership of an issue.
63

64
In [GitLab Starter](https://about.gitlab.com/pricing/), you can
65 66 67 68 69 70
[assign multiple people](multiple_assignees_for_issues.md) to an issue.

#### 4. Epic **[ULTIMATE]**

You can assign issues to an [Epic](../../group/epics/index.md), which allows better
management of groups of related issues.
71

72
#### 5. Milestone
73

74
Select a [milestone](../milestones/index.md) to attribute that issue to.
Marcia Ramos's avatar
Marcia Ramos committed
75

76
#### 6. Time Tracking
Marcia Ramos's avatar
Marcia Ramos committed
77

78 79 80 81
Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../../../workflow/time_tracking.md).
You can add an [estimate of the time it will take](../../../workflow/time_tracking.md#estimates)
to resolve the issue, and also add [the time spent](../../../workflow/time_tracking.md#time-spent)
on the resolution of the issue.
Marcia Ramos's avatar
Marcia Ramos committed
82

83
#### 7. Due date
Marcia Ramos's avatar
Marcia Ramos committed
84

85 86 87
When you work on a tight schedule, it's important to have a way to set a deadline for
implementations and for solving problems. This can be done in the [due date](due_dates.md)
element. Due dates can be changed as many times as needed.
Marcia Ramos's avatar
Marcia Ramos committed
88

89
#### 8. Labels
Marcia Ramos's avatar
Marcia Ramos committed
90

91 92
Categorize issues by giving them [labels](../labels.md). They help to organize workflows,
and they enable you to work with the [GitLab Issue Board](index.md#issue-boards).
Marcia Ramos's avatar
Marcia Ramos committed
93

94 95 96
Group Labels, which allow you to use the same labels for all projects within the same
group, can be also given to issues. They work exactly the same, but they are immediately
available to all projects in the group.
Marcia Ramos's avatar
Marcia Ramos committed
97

98 99 100
TIP: **Tip:**
If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu
from which you can select **Create new label**.
Marcia Ramos's avatar
Marcia Ramos committed
101

102
#### 9. Weight **[STARTER]**
Marcia Ramos's avatar
Marcia Ramos committed
103

104 105 106
[Assign a weight](../../../workflow/issue_weight.md) to an issue.
Larger values are used to indicate more effort is required to complete the issue. Only
positive values or zero are allowed.
Marcia Ramos's avatar
Marcia Ramos committed
107

108
#### 10. Confidentiality
Marcia Ramos's avatar
Marcia Ramos committed
109

110 111 112
You can [set an issue to be confidential](confidential_issues.md). When set, unauthorized
users will not be able to access the issue, and will not see it listed in project
issue boards or the issue list.
Marcia Ramos's avatar
Marcia Ramos committed
113

114
#### 11. Lock issue
Marcia Ramos's avatar
Marcia Ramos committed
115

116 117
You can [lock the discussions](../../discussions/index.md#lock-discussions) in the issue,
to prevent further comments from being added.
Marcia Ramos's avatar
Marcia Ramos committed
118

119
#### 12. Participants
Marcia Ramos's avatar
Marcia Ramos committed
120

121 122
All the users involved in that issue. Either they participated in the [discussion](../../discussions/index.md),
or were mentioned in the description or discussions.
Marcia Ramos's avatar
Marcia Ramos committed
123

124
#### 13. Notifications
Marcia Ramos's avatar
Marcia Ramos committed
125

126 127 128 129 130 131
Click on the icon to enable/disable [notifications](../../../workflow/notifications.md#issue--epics--merge-request-events)
for the issue. This will automatically enable if you participate in the issue in any way.

- **Enable**: If you are not a participant in the discussion on that issue, but
  want to receive notifications on each update, subscribe to it.
- **Disable**: If you are receiving notifications for updates to that issue but no
132
  longer want to receive them, unsubscribe from it.
Marcia Ramos's avatar
Marcia Ramos committed
133

134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151
#### 14. Reference

- A quick "copy to clipboard" button for that issue's reference, which looks like `foo/bar#xxx`,
  where `foo` is the `username` or `groupname`, `bar` is the `project-name`, and
  `xxx` is the issue number.

#### 15. Edit

Clicking this icon opens the issue for editing, and you will have access to all the
same fields as when the issue was created. This icon will not display if the user
does not have permission to edit the issue.

#### 16. Description

The plain text title and description of the issue fill the top center of the issue page.
The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm),
allowing many formatting options.

152
##### Zoom call links
153

154 155 156 157 158 159
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/62966) in GitLab 12.0.

Including a link to a [Zoom](https://zoom.us) call in the description of an issue
results in a **Join Zoom meeting** button at the top of the issue, just under the header.

For example:
160 161 162

![Link Zoom Call in Issue](img/link_zoom_call_in_issue.png)

163 164
To remove the button, edit the description and remove the Zoom call link.

165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
#### 17. Mentions

You can mention a user or a group present in your GitLab instance with `@username` or
`@groupname` and they will be notified via todos and email, unless they have disabled
all notifications in their profile settings. This is controlled in the
[notification settings](../../../workflow/notifications.md).

Mentions for yourself (the current logged in user), will be highlighted in a different
color, allowing you to easily see which comments involve you, helping you focus on
them quickly.

TIP: **Tip:**
Avoid mentioning `@all` in issues and merge requests, as it sends an email notification
to all the members of that project's group, which can be interpreted as spam.

#### 18. Related Issues **[STARTER]**

Issues that were mentioned as [related issues](related_issues.md) are listed here.
You can also click the `+` to add more related issues.

#### 19. Related Merge Requests
Marcia Ramos's avatar
Marcia Ramos committed
186

187 188 189 190
Merge requests that were mentioned in that issue's description or in the issue discussion
thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here.
Also, if the current issue was mentioned as related in another merge request, that
merge request will be listed here.
Marcia Ramos's avatar
Marcia Ramos committed
191

192
#### 20. Award emoji
Marcia Ramos's avatar
Marcia Ramos committed
193

194 195 196
You can award an emoji to that issue. There are shortcuts to "thumbs_up" and "thumbs_down",
or you can click on the light gray "face" to choose a different reaction from the
dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#emoji).
Marcia Ramos's avatar
Marcia Ramos committed
197

198 199 200 201
TIP: **Tip:**
Posting "+1" as a comment in a thread spams all subscribed participants of that issue,
clutters the discussion threads, and is not recommended. Awarding an emoji is a way
to let them know your reaction without spamming them.
Marcia Ramos's avatar
Marcia Ramos committed
202

203
#### 21. Show all activity
Marcia Ramos's avatar
Marcia Ramos committed
204

205 206 207
You can filter what is displayed in the issue history by clicking on **Show all activity**
and selecting either **Show comments only**, which only shows discussions and hides
updates to the issue, or **Show history only**, which hides discussions and only shows updates.
Marcia Ramos's avatar
Marcia Ramos committed
208

209
![Show all activity](img/show-all-activity.png)
Marcia Ramos's avatar
Marcia Ramos committed
210

211
#### 22. Create Merge Request
Marcia Ramos's avatar
Marcia Ramos committed
212

213 214 215 216 217
Create a new branch and [WIP merge request](../merge_requests/work_in_progress_merge_requests.md)
in one action. The branch will be named `issuenumber-title` by default, but you can
choose any name, and GitLab will verify that it is not already in use. The merge request
will automatically inherit the milestone and labels of the issue, and will be set to
close the issue when it is merged.
Marcia Ramos's avatar
Marcia Ramos committed
218

219
![Create MR from issue](img/create_mr_from_issue.png)
Marcia Ramos's avatar
Marcia Ramos committed
220

221 222
Optionally, you can choose to create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue)
only, named after that issue.
Marcia Ramos's avatar
Marcia Ramos committed
223

224
#### 23. Issue history
Marcia Ramos's avatar
Marcia Ramos committed
225

226 227
All comments and updates to the issue are tracked and listed here, but this can be
filtered, as shown above.
Marcia Ramos's avatar
Marcia Ramos committed
228

229
#### 24. Comments
Marcia Ramos's avatar
Marcia Ramos committed
230

231 232
Collaborate in the issue by posting comments in its thread. This text field also fully
supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
Marcia Ramos's avatar
Marcia Ramos committed
233

234
#### 25. Submit Comment, start a discussion, or comment and close
Marcia Ramos's avatar
Marcia Ramos committed
235

236
Once you write a comment, you can:
Marcia Ramos's avatar
Marcia Ramos committed
237

238 239 240 241
- Click **Comment** and your comment will be published.
- Choose **Start discussion** from the dropdown list and start a new [discussion thread](../../discussions/index.md#threaded-discussions)
  within that issue's main thread to discuss specific points. This invites other participants
  to reply directly to your discussion, keeping related comments grouped together.
Marcia Ramos's avatar
Marcia Ramos committed
242

243
![Comment or discussion](img/comment-or-discussion.png)
Victor Wu's avatar
Victor Wu committed
244

245
You can also close the issue from here, so you don't need to scroll to the top of the issue page.