1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
|
---
stage: Create
group: Code Review
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
type: index, reference
---
# Merge request reviews **(FREE)**
[Merge requests](../index.md) are the primary method of making changes to files in a
GitLab project. [Create and submit a merge request](../creating_merge_requests.md)
to propose changes. Your team leaves [comments](../../../discussions/index.md) on
your merge request, and makes [code suggestions](suggestions.md) you can accept
from the user interface. When your work is reviewed, your team members can choose
to accept or reject it.
You can review merge requests from the GitLab interface. If you install the
[GitLab Workflow VS Code extension](../../repository/vscode.md), you can also
review merge requests in Visual Studio Code.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Merge request review](https://www.youtube.com/watch?v=2MayfXKpU08&list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED&index=183).
## Suggested reviewers **(ULTIMATE SAAS)**
> - [Introduced](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/review-recommender/-/epics/3) in GitLab 15.4 as a [Beta](../../../../policy/experiment-beta-support.md#beta) feature [with a flag](../../../../administration/feature_flags.md) named `suggested_reviewers_control`. Disabled by default.
> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/368356) in GitLab 15.6.
> - Beta designation [removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113058) in GitLab 15.10.
GitLab can suggest reviewers. Using the changes in a merge request and a project's contribution graph, machine learning suggestions appear in the reviewer section of the right sidebar.
![Suggested Reviewers](img/suggested_reviewers_v15_9.png)
For more information, see [Data usage in Suggested Reviewers](data_usage.md).
### Enable suggested reviewers
Project Maintainers or Owners can enable suggested reviewers by visiting
the [project settings](../../settings/index.md).
Enabling suggested reviewers triggers GitLab to create an ML model for your
project that is used to generate reviewers. The larger your project, the longer
this process can take. Usually, the model is ready to generate suggestions
within a few hours.
No action is required after the feature is enabled. After the model is ready,
recommendations populate the **Reviewer** dropdown list in the right-hand sidebar
of a merge request with new commits.
## Review a merge request
When you review a merge request, you can create comments that are visible only
to you. When you're ready, you can publish them together in a single action.
To start your review:
1. Go to the merge request you want to review, and select the **Changes** tab.
For more information about navigating the diffs displayed in this tab, see
[Changes in merge requests](../changes.md).
1. Select **Add a comment to this line** (**{comment}**) in the gutter to expand the diff lines
and display a comment box. In GitLab version 13.2 and later, you can
[select multiple lines](#comment-on-multiple-lines).
1. In the text area, write your first comment, then select **Start a review** below your comment.
1. Continue adding comments to lines of code. After each comment, select **Add to review**.
Comments made as part of a review are visible only to you until you submit your review.
1. Optional. You can use [quick actions](../../quick_actions.md) inside review comments.
The comment shows the actions to perform after publication, but does not perform them
until you submit your review.
1. When your review is complete, you can [submit the review](#submit-a-review). Your comments
are now visible, and any [quick actions](../../quick_actions.md) included in
your comments are performed.
If you [approve a merge request](../approvals/index.md#approve-a-merge-request) and
are shown in the reviewer list, a green check mark **{check-circle-filled}**
displays next to your name.
### Download merge request changes as a diff
To download the changes included in a merge request as a diff:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project.
1. Select **Code > Merge requests**.
1. Select your merge request.
1. In the upper-right corner, select **Code > Plain diff**.
If you know the URL of the merge request, you can also download the diff from
the command line by appending `.diff` to the URL. This example downloads the diff
for merge request `000000`:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff
```
To download and apply the diff in a one-line CLI command:
```shell
curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.diff" | git apply
```
### Download merge request changes as a patch file
To download the changes included in a merge request as a patch file:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project.
1. Select **Code > Merge requests**.
1. Select your merge request.
1. In the upper-right corner, select **Code > Patches**.
If you know the URL of the merge request, you can also download the patch from
the command line by appending `.patch` to the URL. This example downloads the patch
file for merge request `000000`:
```plaintext
https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.patch
```
To download and apply the patch in a one-line CLI command using [`git am`](https://git-scm.com/docs/git-am):
```shell
curl "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/000000.patch" | git am
```
### Submit a review
You can submit your completed review in multiple ways:
- Use the `/submit_review` [quick action](../../quick_actions.md) in the text of a non-review comment.
- Select **Finish review**, then select **Submit review** at the bottom of the modal window.
In the modal window, you can supply a **Summary comment**, approve the merge request, and
include quick actions:
![Finish review with comment](img/mr_summary_comment_v15_4.png)
When you submit your review, GitLab:
- Publishes the comments in your review.
- Sends a single email to every notifiable user of the merge request, with your
review comments attached. Replying to this email creates a new comment on the merge request.
- Perform any quick actions you added to your review comments.
- Optional. Approves the merge request.
### Resolve or unresolve thread with a comment
Review comments can also resolve or unresolve [resolvable threads](../index.md#resolve-a-thread).
To resolve or unresolve a thread when replying to a comment:
1. In the comment text area, write your comment.
1. Select or clear **Resolve thread**.
1. Select **Add comment now** or **Add to review**.
Pending comments display information about the action to be taken when the comment is published:
- **{check-circle-filled}** Thread is resolved.
- **{check-circle}** Thread stays unresolved.
### Add a new comment
If you have a review in progress, you can also add a comment from the **Overview** tab by selecting
**Add to review**:
![New thread](img/mr_review_new_comment_v15_3.png)
### Approval Rule information for Reviewers **(PREMIUM)**
When editing the **Reviewers** field in a new or existing merge request, GitLab
displays the name of the matching [approval rule](../approvals/rules.md)
below the name of each suggested reviewer. [Code Owners](../../codeowners/index.md) are displayed as `Codeowner` without group detail.
This example shows reviewers and approval rules when creating a new merge request:
![Reviewer approval rules in new/edit form](img/reviewer_approval_rules_form_v15_9.png)
This example shows reviewers and approval rules in a merge request sidebar:
![Reviewer approval rules in sidebar](img/reviewer_approval_rules_sidebar_v15_9.png)
### Request a new review
After a reviewer completes their [merge request reviews](../../../discussions/index.md),
the author of the merge request can request a new review from the reviewer:
1. If the right sidebar in the merge request is collapsed, select the
**{chevron-double-lg-left}** **Expand Sidebar** icon to expand it.
1. In the **Reviewers** section, select the **Re-request a review** icon (**{redo}**)
next to the reviewer's name.
GitLab creates a new [to-do item](../../../todos.md) for the reviewer, and sends
them a notification email.
## Comment on multiple lines
When commenting on a diff, you can select which lines of code your comment refers
to by either:
![Comment on any diff file line](img/comment-on-any-diff-line_v13_10.png)
- Dragging **Add a comment to this line** (**{comment}**) in the gutter to highlight
lines in the diff. GitLab expands the diff lines and displays a comment box.
- After starting a comment by selecting **Add a comment to this line** (**{comment}**) in the
gutter, select the first line number your comment refers to in the **Commenting on lines**
select box. New comments default to single-line comments, unless you select
a different starting line.
Multiline comments display the comment's line numbers above the body of the comment:
![Multiline comment selection displayed above comment](img/multiline-comment-saved.png)
## Bulk edit merge requests at the project level
Users with at least the Developer role can manage merge requests.
When bulk-editing merge requests in a project, you can edit the following attributes:
- Status (open/closed)
- Assignee
- Milestone
- Labels
- Subscriptions
To update multiple project merge requests at the same time:
1. In a project, go to **Code > Merge requests**.
1. Select **Bulk edit**. A sidebar on the right-hand side of your screen appears with
editable fields.
1. Select the checkboxes next to each merge request you want to edit.
1. Select the appropriate fields and their values from the sidebar.
1. Select **Update all**.
## Bulk edit merge requests at the group level **(PREMIUM)**
Users with at least the Developer role can manage merge requests.
When bulk editing merge requests in a group, you can edit the following attributes:
- Milestone
- Labels
To update multiple group merge requests at the same time:
1. In a group, go to **Code > Merge requests**.
1. Select **Bulk edit**. A sidebar on the right-hand side of your screen appears with
editable fields.
1. Select the checkboxes next to each merge request you want to edit.
1. Select the appropriate fields and their values from the sidebar.
1. Select **Update all**.
## Associated features
These features are associated with merge requests:
- [Cherry-pick changes](../cherry_pick_changes.md):
Cherry-pick any commit in the UI by selecting the **Cherry-pick** button in a merged merge requests or a commit.
- [Fast-forward merge requests](../methods/index.md#fast-forward-merge):
For a linear Git history and a way to accept merge requests without creating merge commits
- [Find the merge request that introduced a change](../versions.md):
When viewing the commit details page, GitLab links to the merge requests containing that commit.
- [Merge requests versions](../versions.md):
Select and compare the different versions of merge request diffs
- [Resolve conflicts](../conflicts.md):
GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI.
- [Revert changes](../revert_changes.md):
Revert changes from any commit from a merge request.
- [Keyboard shortcuts](../../../shortcuts.md#merge-requests):
Access and modify specific parts of a merge request with keyboard commands.
## Troubleshooting
Sometimes things don't go as expected in a merge request. Here are some
troubleshooting steps.
### Merge request cannot retrieve the pipeline status
This can occur if Sidekiq doesn't pick up the changes fast enough.
#### Sidekiq
Sidekiq didn't process the CI state change fast enough. Wait a few
seconds and the status should update automatically.
#### Bug
Merge request pipeline statuses can't be retrieved when the following occurs:
1. A merge request is created
1. The merge request is closed
1. Changes are made in the project
1. The merge request is reopened
To enable the pipeline status to be properly retrieved, close and reopen the
merge request again.
## Tips
Here are some tips to help you be more efficient with merge requests in
the command line.
### Copy the branch name for local checkout
The merge request sidebar contains the branch reference for the source branch
used to contribute changes for this merge request.
To copy the branch reference into your clipboard, select the **Copy branch name** button
(**{copy-to-clipboard}**) in the right sidebar. Use it to check out the branch locally
from the command line by running `git checkout <branch-name>`.
### Checkout merge requests locally through the `head` ref
A merge request contains all the history from a repository, plus the additional
commits added to the branch associated with the merge request. Here's a few
ways to check out a merge request locally.
You can check out a merge request locally even if the source
project is a fork (even a private fork) of the target project.
This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`)
that is available for each merge request. It allows checking out a merge
request by using its ID instead of its branch.
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab
13.4, 14 days after a merge request gets closed or merged, the merge request
`head` ref is deleted. This means that the merge request isn't available
for local checkout from the merge request `head` ref anymore. The merge request
can still be re-opened. If the merge request's branch
exists, you can still check out the branch, as it isn't affected.
#### Checkout locally by adding a Git alias
Add the following alias to your `~/.gitconfig`:
```plaintext
[alias]
mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' -
```
Now you can check out a particular merge request from any repository and any
remote. For example, to check out the merge request with ID 5 as shown in GitLab
from the `origin` remote, do:
```shell
git mr origin 5
```
This fetches the merge request into a local `mr-origin-5` branch and check
it out.
#### Checkout locally by modifying `.git/config` for a given repository
Locate the section for your GitLab remote in the `.git/config` file. It looks
like this:
```plaintext
[remote "origin"]
url = https://gitlab.com/gitlab-org/gitlab-foss.git
fetch = +refs/heads/*:refs/remotes/origin/*
```
You can open the file with:
```shell
git config -e
```
Now add the following line to the above section:
```plaintext
fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
```
In the end, it should look like this:
```plaintext
[remote "origin"]
url = https://gitlab.com/gitlab-org/gitlab-foss.git
fetch = +refs/heads/*:refs/remotes/origin/*
fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*
```
Now you can fetch all the merge requests:
```shell
git fetch origin
...
From https://gitlab.com/gitlab-org/gitlab-foss.git
* [new ref] refs/merge-requests/1/head -> origin/merge-requests/1
* [new ref] refs/merge-requests/2/head -> origin/merge-requests/2
...
```
And to check out a particular merge request:
```shell
git checkout origin/merge-requests/1
```
All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script.
## Cached merge request count
In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than
than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours.
## Related topics
- [Merge methods](../methods/index.md)
- [Draft Notes API](../../../../api/draft_notes.md)
|