The Ultimate Manual to GitLab Pull Requests

Code review is essential for protecting your source code from bugs and flaws when developer teams work on open-source or inner-source projects. For this reason, Git platforms like GitLab use pull requests as the main code-review supporting feature. We’ll explore everything you need to know about working with pull requests in GitLab and how you can adopt this workflow to maintain healthy source code. 

What is a Pull Request Anyway? 

If you’re just starting on GitLab and can’t figure out what a pull request is, it’s not your fault. Pull Request (PR) is a Git term often used interchangeably with Merge Request (MR). Some Git platforms like GitHub and Azure DevOps call them Pull Requests, while others like GitLab call them Merge Requests. 

So a pull request and merge request are just different terminology for the same event. So we’ll also use these terms interchangeably in this post to describe the event. 

A pull request is like a message for collaborators, such as repository maintainers, to review your code before it is pushed or merged to the project’s source code. It is Git’s best practice to incorporate changes to the main repository only when the code has been tested and vetted thoroughly. There’s a lower likelihood of introducing bugs to your source code. 

A PR or MR acts as an isolated platform where the code review occurs. Therefore, anything that happens in the pull request doesn’t affect the main project or source code. Here, developers can discuss the changes, fix bugs, add more features, and test the code without disrupting or altering the source code. 

The code changes are merged to the working version of the software only if everything checks out. Pull requests are a great way of keeping everyone accountable and ensuring that you do not alter the code base or change the user experience unless the changes have been adequately vetted. Finally, pull requests are invaluable for open-source projects with multiple collaborators working on the same base code. 

How GitLab Pull Requests Work

Again, this event is called a Merge Request in GitLab. It is the same as a Pull Request on other platforms, such as GitHub. Here’s how a Pull Request Works in GitLab:

Typical contributors on open-source projects work on many tasks, including bug fixes, new features, and minor or major improvements. Unfortunately, there’s no telling if these changes improve the software or application until integrated into the source code. This situation presents an obvious challenge whereby the code changes may make the software worse, such as introducing bugs to the working version of the code. 

To solve this problem, Git suggests a workflow. For its part, GitLab offers a simplified workflow and supporting features to enable developer teams to follow Git best practices. In short, there are several clearly defined steps a contributor needs to follow before their code changes are merged into the main project.

The feature branching Git workflow is perhaps the easiest to understand in the contest of merge requests. Here, you have a protected main branch, where only a few users can merge changes. All tasks, such as bug fixes or new features, occur in a separate branch pulled from the main branch. 

Developers work on the branch and then open a merge request after completing the changes. It’s also possible to mention other collaborators in the merge request to gather feedback. Collaborators can also make changes to the code to streamline the new feature. Finally, the changes are merged with the manager’s approval into the main branch. 

Personal branching Git workflow also works the same way. However, each developer gets their branch rather than a shared branch to collaborate with team members. This workflow works best when assigning minor bug fixes to specific developers. 

Similarly, you’ll need others to review the code and get permission to merge to the main branch via a merge request. However, you can also use merge requests for other Git workflows that use forking or branching, including Forking Git Workflows and Gitflow Git Workflows. Again, the main idea is to review changes thoroughly before introducing them to the source code. 

Below are a few examples of how pull requests, or merge requests in GitLab, work. 

Example 1: Creating GitLab Merge Requests 

GitLab offers multiple ways to create a merge request. The method you choose depends on what’s most convenient for your workflow. 

For example, you can create a new merge request from the merge request page. Simply navigate your Menu > Projects > New merge request. From here, you can choose the source and target branch. Next, click Compare branches and continue and fill out the required fields to create your merge request. 

Similarly, you can also create a merge request from a current issue. This option is convenient if your workflow requires creating an issue for each merge request. GitLab also automatically closes the issue when the merge request is approved. 

You’ll find the Create merge request button under the issue description. 

Other options for creating merge requests in GitLab include:

• A file you added, edited or uploaded to a repository. 
• From a new branch you made. 
• Using Git commands locally. 
• From a fork, you’re working in. 
• Via email. 

These options ensure that your merge requests are within easy reach regardless of your workflow or project lifecycle stage. You’ll also need to add specific details to your merge requests, including:

• A concise description of the request. 
• Inline code reviews and code changes. 
• Continuous Integration, Continuous Delivery (CI/CD) pipeline information. 
• List of commits. 
• The comment section for the discussion thread. 

Example 2: Assigning Users to a Merge Request 

GitLab assigns the merge request to the person who created it by default. The creator is the author, and this designation doesn’t change. It’s a helpful designation for keeping track of the source of the merge request. 

However, you can assign the MR to another team member known as an assignee in GitLab. The assignee becomes the primary contact person if there are any questions about the MR. Additionally, the assignee is the first person to review the code changes before submitting the changes for approval. 

While most developers can review their code, it’s not always the best option. An extra set of eyes can help find bugs and potential fixes. So it’s common for developers to assign their merge requests to each other. However, It’s worth noting that the assignee doesn’t have the final say on whether the change is merged into the primary branch.  

You can use a text-based shortcut known as a quick action in GitLab to assign an MR to someone else. Simply enter the command /assign @user in your merge request text area to assign the merge request. 

Alternatively, you can assign users by navigating to Menu > Projects > Merge requests > Assignees. The merge request will appear in the user’s assigned merge request list. 

The next step up is the reviewer. As the name suggests, this is the person responsible for reviewing the code. You can also have multiple reviewers and require that each one gives their approval before merging the commit. 

Each reviewer gets a to-do list to help track actions. The author and assignee can also see the status of the review. Finally, proposed changes are only merged once they pass the reviewer’s checks. 

Example 3: Commenting To A Merge Request Diff 

A merge request diff in GitLab shows the difference between the current state of a file and the proposed changes in the merge request. The default view only shows the changed parts of the file. 

GitLab lets you add comments to a merge request diff. The comments are still visible even after amending a comment or force-pushing after a rebase. You can also comment on specific lines of code. 

This feature helps you collaborate with others on your merge request. Team members can quickly provide feedback right in your commits, down to the problematic line of code. 

How to Get Started with GitLab Pull Requests 

The best way to get started with GitLab merge requests is to familiarize yourself with code review best practices. Merge requests are an integral part of code review, so it makes sense to start here. 

Conduct Automated Code Checks before Merge Requests 

It’s good for all developers to perform automated code checks before opening new merge requests. This practice helps to reduce the review time. Additionally, automated checks can catch spacing issues, function name errors, and other overt formatting mistakes. 

Then, reviewers can focus on interpretive or stylistic errors. GitLab has built-in CI/CD functionality to test your code. GitLab also lets you embed your code quality report in your merge request to make the work even easier for reviewers. 

GitLab also supports third-party code review tools for this purpose. These tools can help to enhance your native GitLab functionality. For instance, a robust code review tool may offer actionable suggestions for remediating bugs and security issues. 

Create Small Merge Requests 

Merge requests take time to review. So a large merge request may be off-putting for reviewers. They’ll need to block off large chunks of time to review big merge requests, which can create unnecessary delays. 

The best way to keep your merge request concise is to address only one concern at a time. Then, consider creating separate merge requests for different concerns. For example, you can have independent MRs for fixing the current code and adding new functionality. 

The less contentious commits get approved faster and integrated into the codebase. Following the previous example, you may find that the team welcomes your new functionality, but there are discussions around your code fixes. You may have to wait for all concerns to be resolved before merging your code. 

Your improvements could have already been adopted if they were on a different merge request.  

Similarly, assigning unrelated changes to the right team members is more manageable. So, again, the light code updates might be assigned to a junior developer. Then the more contentious fixes might be given to more experienced team members. 

Finally, your merge request shouldn’t cover more than a dozen files as a rule of thumb. Also, try to limit your line width to 80 characters. Again, this makes your code easier to view on a diff tool. 

Offer Context for Your Merge Request 

Reviewers don’t have the same context level as the merge request authors. This is because they didn’t write the code or spend hours mauling over the solution. So it is crucial to provide as much context as possible in the merge request to create a smoother review process. 

Creating context starts with writing a good description. The description should include who, how, and why. For example, your description should indicate what the merge request attempts to accomplish, an overview of your solution, and a rationale for your method or approach.

GitLab also lets you add images and videos to merge requests. This feature helps clarify complex logic with sequence diagrams, images, or screenshots of the UI. Again, visual cues make it easier for reviewers to understand your task. 

GitLab also comes with built-in merge request description templates to help you standardize your MR layouts. Alternatively, you can create templates from scratch and upload them to GitLab. Finally, it’s worth creating templates for different workflows, such as bug reports, feature proposals, and feature improvements. 

Prioritize What to Review in Merge Requests 

The typical merge request may have many potential flaws. These include minor flaws like incorrect indentation or typos to major problems like the code doesn’t work as it should, or there’s a security hole in the code. Therefore, it’s important to prioritize what to review in your MRs. 

The first priority should be the core functionality. Some of the questions to ask include:

• Does the code work as it should?
• Does it do something it shouldn’t do?
• Are there additional tests available or required for the new code?
• Has the documentation been updated?
• Do we need to perform specific actions, such as changing the data schema or updating the version number?

The second priority pertains to security. Some of the security-related questions to go through when reviewing merge requests include:

• Are the errors appropriately resolved?
• Are there any security flaws in the code?
• Can the program crash?
• Is the thread safe?
• Are there memory leaks or other resource leaks?

Next, review the code performance. You’ll look at aspects such as programming methodology, reliability, and speed. Some of the questions to ask include:

• Is the code necessary for the project, or was it tacked on? 
• Does the code conform to your organization’s framework or programming language?
• Is there duplicate code?
• Are there existing libraries to shorten the code?
• Are there unnecessary elements that slow down the code?

Finally, consider whether the code conforms to the outlined coding conventions. Possible areas of concern here include:

• Unnecessary trailing whitespace. 
• Spaces vs. tabs. 
• Code formatting such as line wrapping and curly braces placement. 
• The naming of variables. 
• Grammatical mistakes and typos in the comments and strings.