Review Source Code with Merge Requests

The review of the source code helps in avoiding bugs, identifying design issues, and catching design and implementation problems that might affect the application performance. To get the source code reviewed, you must create a merge request.

Merge Requests Concepts and Terms

As the name suggests, a merge request is a request to merge a branch into another. Before merging the branch, you may want your team members to review updates made to the branch and share their feedback. A merge request combines the review and merge processes into one easy collaborative process.

You can also link related issues and builds to the merge request that are automatically updated or triggered when you merge branches.

Here are the terms that this documentation uses to describe the merge request features and components.

Term	Description
Review branch	Branch to be reviewed and merged.
Target branch	Branch that the review branch will merge into.
Reviewer	Project user invited to review the changed files of the review branch.
Requester	Project user who created the merge request.
Subscriber	Project user who isn’t a reviewer, but is watching the merge request.
Default reviewer	Project user who’s automatically added as a reviewer if a branch is selected as the review branch. Only a project owner can create default reviewers of a branch.
Approved	Reviewer's feedback with no objection to the changes made to the source code in the review branch.
Rejected	Reviewer's feedback with objections to changes made to the source code in the review branch and a recommendation not to merge the review branch into the target branch.
General comment	A comment in the Conversations tab of the merge request.
Inline comment	A comment added to a line of a file under review.
Pending (or unpublished) comment	An inline comment that you didn’t publish when you added it.

To understand the workflow of a merge request, let's consider you're a software developer assigned a new feature to implement. These steps summarize the action you’d perform to set up a merge request and merge branches.

1. Create a branch from a stable branch (say master) of the source code Git repository. You'd add or update the files of the new branch to implement the new feature.

   You can do this in the cloned Git repository on your computer or on the DevCS Git page.

2. On your computer, pull the latest content from the project’s Git repository, checkout the new branch, update the required files, and commit and push the checked out branch to the project’s Git repository.

3. If required, create a build job to generate artifacts from the new branch to verify the stability of the application.

4. Create a merge request with the new branch as the review branch and the stable branch as the target branch.

5. Add your manager and other team members as reviewers.

6. To resolve the feature related issues when you close the merge request, link the issues to the merge request.

7. Depending on the review feedback, you may need to update some files and check the stability of the branch. To trigger a build of the job automatically when you update the files of the review branch, link the job to the merge request.

8. Again, based on the feedback and build status of the linked jobs, you may want to merge the branch with the stable branch or abandon it. If you merge the branches, the linked issues are automatically resolved.

If you're invited to a merge request, you can add comments to the updated files, and share your feedback whether you’ve any objection to merge branches.

1. Open the merge request.

2. Check the commits made to the review branch and compare the changed files.

3. Add general or inline comments, if necessary.

4. Submit your feedback as Approved if you find the code updates acceptable, or Rejected if you have objections.

If you're a project member but aren’t invited to a merge request, you can add comments but you can't share your feedback.

It isn’t necessary to add reviewers to a merge request. If you're sure that the changes made to the review branch don’t require a review, you can merge both branches without a review. If you're comfortable using Git, you can merge branches from a Git client or from an IDE without creating a merge request.

Merge Request States

A merge request can be in one of various states such as Open, Merged, or Closed.

State	Description
Open	Code review is in progress. A merge request’s status remains Open until the branches are merged or the request is closed.
Merged	Code review is complete and the review branch has been merged with the target branch. The review is closed for inline comments, but can accept general comments.
Closed	Code review is closed without merging the review branch with the target branch. The review is closed for inline comments, but can accept general comments.

Create and Manage Merge Requests

After you create a merge request, you add reviewers and link related issues and jobs to it.

Create a Merge Request

You can create a merge request from the Merge Request page. You can't create a merge request if the branch that you want to be reviewed has any merge restrictions set or is already under review in another merge request.

You must be a project member to create a merge request.

1. In the navigation bar, click Merge Requests .
2. Click + Create Merge Request.
3. On the Branch page of the New Merge Request wizard, in Repository, specify the Git repository.
4. In Target Branch, select the branch that the review branch would merge into.
5. In Review Branch, select or enter the name of the branch to be reviewed. If the branch doesn’t exist, it’s created.
   If the review branch is already under review in another merge request, the branch name won’t appear in the Review Branch list.
6. Click Next.
7. On the Details page of the New Merge Request wizard, in Linked Issues, add issues related to the merge request.
   When merging branches or closing the merge request, you can choose to mark the linked issues as resolved.
8. In Linked Builds, add jobs related to the merge request.
   Builds of the linked jobs run automatically when the review branch is updated.
9. In Tags, add project tags to associate them with the merge request.
   You can use these tags to search merge requests.
10. In Summary, enter a summary (or title) of the merge request. If not specified, the default summary Merge Request for branch <review_branch_name> is set.
11. In Reviewers, select team members who’ll review the updates.

    Names of default reviewers are added automatically, however, you may choose to remove them.

    To add all reviewers of the last merge request you created, select Reviewers .

12. Click Next.
13. On the Description page of the New Merge Request wizard, enter a description, and click + Create.
    You can use the project’s wiki markup to format the description.

After the merge request  is created, all reviewers are assigned the Reviewer role and you're assigned the Requester role. Email notifications are also sent to reviewers informing them that they are added as reviewers.

Add or Remove Reviewers

You can add reviewers when you create a merge request or while the review is open. You must be the requester or a reviewer to add or remove reviewers.

1. In the navigation bar, click Merge Requests .
2. Click the merge request summary to open it.

You can manage the reviewers from the Review Status section available on the right side of the page.

Action	How To
Add a reviewer	In the Review Status section, click Click to add a reviewer. In the Add Reviewer list, enter the project member name or select the member from the list. Click Save .
Add yourself as a reviewer	If you're a project member but not a reviewer, you can submit a request to add yourself as a reviewer to a merge request. Above the Review Status section, click Add me . If you’re a project owner, you are added immediately to the merge request. If you’re a project member, then enter a justification in the Request to be added as a reviewer dialog box, and click OK.
Approve a reviewer request	If you’re the requester or a reviewer, you can approve requests of project users to join the merge request as reviewers. In the Conversation tab, click Add User in the requested to be a reviewer request.
Remove a reviewer	In the Review Status section, click Remove next to the reviewer you want to remove.

Link an Issue to a Merge Request

Linking issues to a merge request enables you to resolve them automatically when you merge or close a merge request.

1. Open the merge request.
2. Click the Linked Issues tab.
   The tab displays issues linked to the merge request.
3. To link an issue to the merge request, enter the issue summary text or the issue ID in the Search and Link Issues search box, select the issue from the drop-down list, and click Save .

If an external Jira server is linked with a project, you can also link Jira issues with the merge request. Select the Jira issues from the window that opens when you click the Search and Link Issues search box. Contact the project Owner to know more about the linked external Jira server.

Link a Build Job to a Merge Request

Linking build jobs to a merge request enables you to monitor them from the merge request and trigger them when a commit is pushed to the review branch. Depending on the build’s status, reviewers can determine whether the merge request is ready to be merged with the target branch.

1. Configure the job to accept merge request parameters.
   See Use Build Parameters.
2. Open the merge request.
3. Click the Linked Builds tab.
   The tab displays linked jobs, if any.
4. In Search and Link Build Jobs, enter the job name and select it from the list.
5. Click Save .

After a job is linked to a merge request, a build automatically runs when the review branch is updated with a commit.

When a build of a linked job runs, a comment is automatically added to the Conversation tab. If the build succeeds, it auto-approves the merge request and adds itself to the Approve section of the Review Status list. If the build fails, it auto-rejects the merge request and adds itself to the Reject section of the Review Status list.

Watch a Merge Request

You can set up a watch on a merge request and get email notifications when a reviewer adds a comment, a user updates files of the review branch, or a reviewer shares a feedback.

Action	How To
Merge requests where you’re a reviewer	By default, you get email notifications of merge requests where you’re a reviewer. If you aren’t getting the email notifications, select the Merge Request updates and comments check box in your user preferences page. In the branding bar, click the user avatar, and select Preferences. Click the Notifications tab. Select the Merge Request updates and comments check box, if not selected. To the left of the User Preferences title, click Close to return to the last opened page.
Merge requests where you’re not a reviewer	Open the merge request. Click CC me. To stop watching, remove your name from the Watchers list.

Merge Request Email Notifications

As the reviewer, the requester, or the subscriber (watcher) you receive email notifications when the merge request is created or updated. A notification of the event also appears in the Recent Activity feed on the Project Home page.

Some events that send notifications are:

• Merge request is created

• Additional source code changes are committed to the review branch and pushed to the upstream

• A general comment is added

• An inline comment is published

• Reviewers are added or removed

• Merge request is approved or rejected

• Merge request is closed or merged

Batch emails are sent when:

• A user submits multiple inline comments

• A user submits several private inline comments and publishes them later

• A user submits several general comments in a short duration

• Multiple users carry on multiple conversations at the same time in different inline comments

• Multiple users carry on multiple conversations in general comments

Batch emails are also sent for review events that occurred before the inactivity period, which is usually five minutes after users stop entering comments. Review activities, other than comments related activities, don’t send email notifications in the inactivity period. A batch email is sent after the inactivity period listing all review activities that happened prior to the period of inactivity expires.

Review a Merge Request

To review a merge request, on the Merge Request page, click its summary. On the Review page, you can view the commits of the review branch, review changed files, add inline and general comments, and submit your feedback.

Open a Merge Request

To open a merge request, on the Merge Requests page, click its name.

Use the filter tabs to search for the merge request. By default Related To Me, Waiting for Approval, Created By Me, Open, and Merged filters are available. More filters are available in the More drop-down list.

Description of the illustration devcs_mergerequests.png

If you’re invited to a merge request, you can also click the request ID from the email notification.

Description of the illustration devcs_mergerequest_email.png

If you still can’t find the merge request through the available filters, use the search box at the top of the page or click New Search to run an advanced search.

You can also save the advanced search for future use. In Search Name, enter a name and click Save. The saved searches are listed in the More drop-down list.

View Commits and Changed Files

You can view commits and changed files from the Commits and the Changed Files tabs.

The Commits tab shows all commits made to the review branch. This table lists the common actions you can perform from the Commits tab.

Action	How To
Compare the files of one commit with another	Click the button with the first seven characters of the commit’s SHA-1 checksum hash. By default, the page compares the commit with the previous commit.
View all files of the repository when the commit was pushed to the branch	Click Code.
View files that were updated in the commit	Click Show Details. To compare a file with its parent commit, Click the file name to compare the file changes with its previous commit.

The Changed Files tab shows the files in the compare mode. This table lists the common actions you can perform from the Changed Files tab.

Action	How To
Open a tree view of changed files	Click Changed Files Tree .
View the compare options	Click Diff Preferences .
Add a comment to a code line or reply to one	Mouse-over the line number of the file and click Add Comment.

Add a General Comment

In the Conversation tab, you can view the ongoing conversation and add comments. The comment could be a generic comment, a question you want to ask reviewers, or a comment about an event such as a commit.

1. Open the merge request.
2. In the Write tab of the Conversation tab, enter your comment.
   You can use the project’s wiki markup to format the comment. Click the Preview tab to preview the format.
3. Click Submit.

The comment adds in the Conversation tab along with icons to reply, edit, and delete your comment. Note that you can’t edit or delete comments entered by other users.

Add an Inline Comment to a File

When a code review is in progress, you can add inline comments directly to a file’s code lines. You can’t add an inline comment after a merge request has been merged or closed.

1. Open the merge request.
2. Click the Changed Files tab.
3. Mouse-over the line number of the file and click Add Comment.
   
   Description of the illustration odcs_addreviewcomment.png
4. Add your comment in the comment box.

   • Use the project’s wiki markup language to format the comment.

   • Click Comment to publish it and make it visible to all reviewers.

     You can’t edit or delete a published comment.

   • Click Save to save the comment and publish it later. The comment isn’t published and isn’t visible to reviewers.

   • Click Cancel to cancel the comment.

To view your pending or unpublished comments, click the Pending Comments tab.

To reply to a published comment, click Reply , enter your comment, and click Comment. Comment replies to a published comment are published immediately and can’t be edited or deleted.

Manage Unpublished Comments

The Pending Comments tab displays all pending comments with the code where these comments were added. The comments appear inline in the code.

• To edit a comment, click Edit .

• To publish a pending comment, click Publish to the right side of the comment header.

• To publish all pending comments, click Publish All.

• To discard all pending comments, click Discard All.

• To delete a comment, click Delete .

Approve or Reject a Merge Request

As a reviewer, after you review the source code, you can add a special comment that indicates whether you approve the code changes or reject them. Approving a merge request implies that you don’t have any objections to changes made to the source code. Similarly, rejecting a merge request implies that you’ve an objection and don’t recommend merging branches.

Note that if you created the merge request, but didn’t add yourself as a reviewer, you can’t approve or reject the merge request. However, you can still close it or merge it with the target branch.

1. Open the merge request.
2. Click the Approve or Reject button at the right side of the page.
3. In the dialog box that appears, add your comment, and click OK.
   Use the project’s wiki markup to format the comment.

You can see your feedback (approval or rejection) in the Reviewers list.

Merge Branches and Close the Merge Request

After addressing reviewers’ comments, you can decide whether to merge the branches or cancel the request.

Before doing that, go to the Review Status section and check the review status for the reviewers and the status for linked build jobs. Depending on the number of Approves, Rejects, and No Response, you can decide whether you want to merge the review branch, wait for more approvals, or cancel the request.

Merge Branches

There are various ways to merge the review branch into the target branch. You can merge commits, squash and merge, rebase and merge, or merge the branches manually. To merge branches, you must be assigned either the reviewer role or the requester role of the merge request.

It isn’t mandatory to get approval from all reviewers before you merge the review branch. Note that you can’t merge the review branch if the target branch is locked and must contact the project owner to unlock the target branch.

1. Open the merge request.
2. On the right side of the page, click Merge.
3. In the Merge dialog box, click Merge Options, and select the merge type.

   Use this merge type ...	To:
   Create a merge commit	Merge all commits of the review branch to the target branch. The merge commits continue to show two parents.
   Squash and Merge	Add the commit history of the review branch to the target branch as a single commit.
   Rebase and Merge	Reapply the commits of the review branch and add them to the top of the target branch.
   Manual Merge	Follow the on-screen commands to merge the branches using the Git CLI.

   At the top of the dialog box, select the Remember My Choice check box to pre-select the current option next time you open the Merge dialog box.

4. If necessary, update the Merge Summary and Merge Description.
   The fields aren’t available if you select Rebase and Merge or Manual Merge.
5. To delete the review branch after the commits are merged with the target branch, select the Delete Branch.
6. If there are any linked issues, deselect the check boxes of the issues that you don’t want to mark as resolved after the commits are merged with the target branch. By default, check boxes of all linked issues are selected.
7. Submit the dialog box.

After the review branch has been merged, the merge request is automatically closed and no other action is allowed.

If you didn’t select the Delete branch check box when you merged the review branch, note that the review branch wasn’t removed from the Git repository. You can continue to make commits to the branch and create another merge request to review the new source code.

Resolve a Merge Conflict

Git can automatically resolve code conflicts when the review branch is merged with the target branch. In some cases, however, the conflicts must be resolved manually.

On the Merge Request page, if the Merge button is replaced by the Show Merge Conflicts button, it indicates a merge conflict.

Git automatically resolves conflicts if different files of the target and review branches are updated before both branches are merged. Merge conflicts are reported when the same lines of the same files are updated in the review branch and the target branch before both branches are merged. In such cases, you have to manually review each conflicting file in the review branch with the code of the same file in the target branch and resolve the conflicting code lines. To find and resolve the conflicting files, run the Git commands that the merge request page shows.

1. Open the merge request.
2. Click Show Merge Conflicts.
   A Merge Conflicts dialog box opens with the commands you need to run to resolve the conflict. It also lists the conflicting files.
3. On your computer, open the Git CLI.
4. If you’ve already cloned the project Git repository, navigate to its directory.
   If you haven’t cloned the Git repository, clone it.
5. Run the commands shown on the Merge Conflicts dialog box.
   The commands help you resolve the conflict and mark the conflicting code lines in files.
6. Open each file with conflicts in a text editor or an IDE.
   The conflict content are marked with <<<<<<<, =======, and >>>>>>>. The lines between <<<<<<< and ======= show the code from the target branch. The lines between ======= and >>>>>>> show the code from the review branch.
7. Review the content and update it. Remember to remove the <<<<<<<, =======, and >>>>>>> from each conflicting file before saving it.
8. Save all files and commit them.
   Run the git status command to view the status of conflicting files.
9. Push the commit to the target branch.

Conflicting files of the review branch are now merged with the target branch. No additional action is required on the Merge Request page.

If you want to delete the review branch, open or refresh the merge request page, and click Delete Branch.

Close a Merge Request

You must close a merge request after the review branch has been merged. To close a merge request, it isn’t necessary to merge the review branch to the target branch. You can close a merge request if it was created by mistake or if you don’t want to merge the review branch to the target branch.

Make sure that you perform any needed merge action before you close the request. Once a merge request is closed, you can’t merge the review branch, add comments, or review the source code.

1. Open the merge request.
2. Click Close.
3. Complete the elements of the Close Merge Request dialog box.

   To change the review status to Merged and close the review, select the Close as Merged check box. You may choose the Close as Merged option if the review branch was merged through some other means (such as the Git CLI, IDE, or though the git cherry-pick command).

   If you don’t select the Close as Merged check box, the Merge Request is closed without changing the review status to Merged. You may want to do this if the merge request was created on the wrong branch or created by mistake.

4. Click OK.

Merge Request and Branch Administration

On a Git repository branch, you can set some restrictions and assign some project users as default reviewers of the branch

For a branch, you can set rename, delete, push, and merge restrictions; or lock a branch if you don’t want anyone to push commits to it or merge another branch with it. When a merge request is created with the branch as the target branch, the default reviewers of the branch are automatically added to the Reviewers list.

You must be assigned the project Owner role to assign default reviewers to a branch, or set push and merge restrictions on it. For a Private branch, a branch owner can also change its restrictions.

Set Review and Merge Restrictions on a Repository Branch

You can configure a branch to allow another branch to merge into it only through a merge request after the merge request has specified number of approvals.

The number of approvals ensures that specified reviewers of the merge request have reviewed the changes of the review branch. You can't merge a branch outside DevCS, such as using a Git client, without meeting the number of approvals requirement of the merge request. You can set other review restrictions on a branch, such as whether the last build of the branch must be successful to merge it.

You must be assigned the project Owner role to set review restrictions on a branch.

1. In the navigation bar, click Project Administration .
2. Click Branches.
3. In Repository and Branches, select the Git repository and the branch.
4. Select the Requires Review option.

When you select the Requires Review option for branch, you can merge a branch after the branch's approvals requirement is met.

This table describes the other review restrictions you can set from the Branches page.

Action	How To
Assign default reviewers to a branch	A default reviewer is a project member who is automatically added as a reviewer when a merge request is created on a branch. In Reviewers, enter and select the users.
Set minimum number of approvals before a branch is merged to the selected branch	From the Approvals drop-down list, select the minimum number of reviewers who must approve the review branch of a merge request where the selected branch is the target branch.
Allow a review branch to be merged to the selected branch only if the last build of the linked job in Merge Request is successful	Select the Require successful build check box.
If a change is pushed to a branch after some reviewers have approved the merge request, merge only when they reapprove the merge request	Select the Reapproval needed when branch is updated check box.
Ensure changes pushed to the target branch match the contents of the review branch	Select the Changes pushed to target branch must match review content check box
Specify users who can bypass the branch restrictions and merge the review branch of a merge request outside DevCS or without required approvals	In Merge Request Exempt Users, specify the users. This is useful if you want to allow some users to merge the review branch irrespective of review conditions being met.