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.
-
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.
-
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.
-
If required, create a build job to generate artifacts from the new branch to verify the stability of the application.
-
Create a merge request with the new branch as the review branch and the stable branch as the target branch.
-
Add your manager and other team members as reviewers.
-
To resolve the feature related issues when you close the merge request, link the issues to the merge request.
-
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.
-
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.
-
Open the merge request.
-
Check the commits made to the review branch and compare the changed files.
-
Add general or inline comments, if necessary.
-
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.
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.
- In the navigation bar, click Merge Requests .
- 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 |
|
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.
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.
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.
|
Merge requests where you’re not a reviewer |
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.
If you’re invited to a merge request, you can also click the request ID from the email notification.
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.
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.
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.
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.
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.
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.
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.
- In the navigation bar, click Project Administration .
- Click Branches.
- In Repository and Branches, select the Git repository and the branch.
- 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. |