GitLab's Merge Requests are your chance to review code before it enters your project's main branch. A Merge Request (MR) is a wrapper around a

        git merge
    

operation that's accessible within the GitLab web UI. Once you've reviewed your code, you can initiate the merge with a single click. Adopting an MR-driven workflow helps you guarantee code quality by creating an expectation that all commits are thoroughly reviewed.

Merge Requests are one of the foundational elements of the GitLab experience. They combine its project management, repository and CI/CD systems into a single page for each change in your codebase. We're using the open-source GitLab CE in this article. Commercial tiers have access to additional features.

Creating a Merge Request

You can create a new MR from within GitLab by navigating to Repository > Branches in the sidebar. Make sure you've pushed the changes on your local branch up to GitLab. Find the branch you'd like to merge and click the "Merge request" button to the right of its name.

Use the form to define the properties of your merge request. Start by titling your new MR. Next, add a description. Standards for descriptions vary by organisation and by project. In general, you'll want to note down any important changes you've made, as well as the reasoning behind them.

At the bottom of the page, you'll find controls for setting the MR's assignee, reviewer, milestone and labels. These can be amended at any time using the right sidebar on the merge request details page. We'll cover them in more detail later on.

You can complete an initial review without submitting your MR. Use the "Commits" and "Changes" tabs to confirm you've included the correct code. Once you're ready, hit the green "Submit merge request" button to open the MR. You can view all the MRs in your project using the "Merge Requests" link in the sidebar.

Creating Merge Requests from Your Terminal

Creating MRs through the GitLab UI encourages you to accurately tag the MR with labels, milestones and descriptive text. Nonetheless, it's a laborious process which can consume substantial time through the day. GitLab supports Git push options that allow you to push a branch and create an MR at the same time.

git push -u origin HEAD -o merge_request.create -o merge_request.target=master

Using git push with the options shown above will push your current branch to your Git remote. The remote branch will be created anew, using the same name as your local branch, if it doesn't already exist. The two -o options will be processed by GitLab. They'll result in a new MR being opened to merge your branch into master.

GitLab will automatically populate the MR's title and description using information from your latest commit. In addition, you can reference a GitLab issue in your commit message - e.g. Fixes #123 - to have GitLab automatically apply its labels and milestones to the MR.

Reviewing Merge Requests

No code is complete until it's been reviewed. You can easily request others in your group to give your commits the once-over. Use the right sidebar to select one or more reviewers. They'll be notified of your request.

You may also assign your MR to another user. This might indicate that they need to update their areas of responsibility to add compatibility with your changes. There's no hard-and-fast rules on how you should use these features.

When you're tasked with reviewing an MR, switch to the "Commits" and "Changes" tabs at the top of the screen. The former gives a list of all the new commits on your branch while the latter presents the file diffs to apply to the codebase.

You can adjust the layout of the Changes screen using the settings cog in the top-right. You can choose between Inline and Side-by-Side diffs, the latter displaying the "old" and "new" versions of files in a split view. You can help yourself focus, and improve the screen's performance, by enabling the "Show one file at a time" option.

Making Changes to Your Code

Despite all your best efforts, sometimes you'll review your MR and discover an issue you hadn't spotted before. You don't need to head straight back to your code editor though. The Changes screen has provisions available to help you correct errors as you find them.

For simple one-line fixes, hover over the line in question. Click the comment icon that appears to the left of the line. The comment editor will appear, featuring GitLab's standard Markdown editor. You can use this facility to comment on specific lines in your MR - your messages will appear back on the "Overview" tab. We're looking for a specific feature though, the "Insert suggestion" button on the toolbar.

Click the button to insert the selected line into your comment. Use the comment editor to edit the line to what it should look like. Next, click either "Start a review" or "Add comment now". The former lets you hold multiple comments together to submit as a batch once you've completed your review.

Once you've saved your comment, you'll see a "Suggested change" widget appear below the suspect line. This will display the new diff to apply. Click the "Apply suggestion" button to instantly add your change.

Using Suggestions can dramatically reduce the time to fix minor issues as you don't need to leave your browser. For longer edits, you may click the three dots icon next to any file on the Changes screen to open it in the full GitLab Web IDE.

Draft (Work-in-Progress) Merge Requests

Sometimes you'll want to push code before it's ready to merge. You can distinguish these MRs by prefixing their title with "Draft" or clicking the toolbar button. Draft MRs cannot be merged until you manually revoke their draft status by clicking "Mark as ready" in the top-right.

This functionality used to be called "Work-in-Progress," using the "WIP" title prefix. That terminology has now been abandoned in favour of "Draft," which will be the only supported variant in GitLab 14. Both forms are available in GitLab 13.

As you add commits to your MRs, they'll be listed on the Overview section of the MR page. You can click the "Compare with previous version" link to see the diff of these changes in isolation.

Clicking the "Changes" tab without choosing a version displays the diff of the entire MR relative to the target branch. You can view the diff of any two versions using the "Compare [master] and [latest version]" dropdowns at the top of the Changes screen.

Completing Your Review

Once you've completed your review, it's time to merge your code. You'll need to revoke the MR's Draft status if it's been set. Depending on your project's settings, you might also have to "resolve" any comment threads which have been created.

To signal the MR is ready to be merged, use the blue "Approve" button. This doesn't take any action within GitLab except signalling to your team that the MR has been accepted. You can then go ahead and merge the MR by pressing the green "Merge" button.

Use the "Delete source branch" checkbox to control whether the branch gets deleted after the merge. This helps keep your branches list lean but could lead to loss of context in the future. The "Squash commits" option lets you combine all the commits in the MR into one. This creates a tidier commit history but will make it harder to revert individual changes in the future. The availability of these options will depend on settings defined within your project and your group.

Merge Requests provide a good structure for writing and reviewing code. At the same time, they're extremely flexible and open to interpretation. It's up to you how far you develop your merge request workflow.

In this article, we've only looked at the features directly relevant to a code reviewer. You might see much more information in your merge requests if you make use of GitLab's other features. The Overview page can exhibit CI pipeline status, test and code quality reports, security scan outputs and staging environment links, all of which make the MR page your first destination when understanding how a change will impact your project.