Merge requests

Merge requests allow you to visualize and collaborate on the proposed changes to source code that exist as commits on a given Git branch.

Merge request view

A Merge Request (MR) is the basis of GitLab as a code collaboration and version control platform. It is as simple as the name implies: a request to merge one branch into another.

Use cases

A. Consider you are a software developer working in a team:

  1. You checkout a new branch, and submit your changes through a merge request
  2. You gather feedback from your team
  3. You work on the implementation optimizing code with Code Quality reports
  4. You verify your changes with JUnit test reports in GitLab CI/CD
  5. You avoid using dependencies whose license is not compatible with your project with License Compliance reports
  6. You request the approval from your manager
  7. Your manager:
    1. Pushes a commit with their final review
    2. Approves the merge request
    3. Sets it to merge when pipeline succeeds
  8. Your changes get deployed to production with manual actions for GitLab CI/CD
  9. Your implementations were successfully shipped to your customer

B. Consider you’re a web developer writing a webpage for your company’s website:

  1. You checkout a new branch, and submit a new page through a merge request
  2. You gather feedback from your reviewers
  3. Your changes are previewed with Review Apps
  4. You request your web designers for their implementation
  5. You request the approval from your manager
  6. Once approved, your merge request is squashed and merged, and deployed to staging with GitLab Pages
  7. Your production team cherry picks the merge commit into production

Overview

Merge requests (aka “MRs”) display a great deal of information about the changes proposed. The body of an MR contains its description, along with its widget (displaying information about CI/CD pipelines, when present), followed by the discussion threads of the people collaborating with that MR.

MRs also contain navigation tabs from which you can see the discussion happening on the thread, the list of commits, the list of pipelines and jobs, the code changes and inline code reviews.

Merge request navigation tabs at the top

Introduced in GitLab 12.6. This positioning is experimental.

So far, the navigation tabs present in merge requests to display Discussion, Commits, Pipelines, and Changes were located after the merge request widget.

To facilitate this navigation without having to scroll up and down through the page to find these tabs, based on user feedback, we are experimenting with a new positioning of these tabs. They are now located at the top of the merge request, with a new Overview tab, containing the description of the merge request followed by the widget. Next to Overview, you can find Pipelines, Commits, and Changes.

Merge request tab positions

Please note this change is currently behind a feature flag which is enabled by default. For self-managed instances, it can be disabled through the Rails console by a GitLab administrator with the following command:

Feature.disable(:mr_tabs_position)

Creating merge requests

While making changes to files in the master branch of a repository is possible, it is not the common workflow. In most cases, a user will make changes in a branch, then create a merge request to request that the changes be merged into another branch (often the master branch).

It is then reviewed, possibly updated after discussions and suggestions, and finally approved and merged into the target branch. Creating and reviewing merge requests is one of the most fundamental parts of working with GitLab.

When creating merge requests, there are a number of features to be aware of:

FeatureDescription
Adding patches when creating a merge request via e-mailAdd commits to a merge request created by e-mail, by adding patches as e-mail attachments.
Allow collaboration on merge requests across forksAllows the maintainers of an upstream project to collaborate on a fork, to make fixes or rebase branches before merging, reducing the back and forth of accepting community contributions.
AssigneeAdd an assignee to indicate who is reviewing or accountable for it.
Automatic issue closingSet a merge request to close defined issues automatically as soon as it is merged.
Create new merge requests by emailCreate new merge requests by sending an email to a user-specific email address.
Deleting the source branchSelect the “Delete source branch when merge request accepted” option and the source branch will be deleted when the merge request is merged.
Git push optionsUse Git push options to create or update merge requests when pushing changes to GitLab with Git, without needing to use the GitLab interface.
LabelsOrganize your issues and merge requests consistently throughout the project.
Merge request approvals Set the number of necessary approvals and predefine a list of approvers that will need to approve every merge request in a project.
Merge Request dependencies Specify that a merge request depends on other merge requests, enforcing a desired order of merging.
Merge Requests for Confidential IssuesCreate merge requests to resolve confidential issues for preventing leakage or early release of sensitive data through regular merge requests.
MilestonesTrack merge requests to achieve a broader goal in a certain period of time.
Multiple assignees Have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it.
Squash and mergeSquash all changes present in a merge request into a single commit when merging, to allow for a neater commit history.
Work In Progress merge requestsPrevent the merge request from being merged before it’s ready

Reviewing and managing merge requests

Once a merge request has been created and submitted, there are many powerful features that you can use during the review process to make sure only the changes you want are merged into the repository.

For managers and administrators, it is also important to be able to view and manage all the merge requests in a group or project. When reviewing or managing merge requests, there are a number of features to be aware of:

FeatureDescription
Bulk editing merge requestsUpdate the attributes of multiple merge requests simultaneously.
Cherry-pick changesCherry-pick any commit in the UI by simply clicking the Cherry-pick button in a merged merge requests or a commit.
Commenting on any file line in merge requestsMake comments directly on the exact line of a file you want to talk about.
Discuss changes in threads in merge requests reviewsKeep track of the progress during a code review by making and resolving comments.
Fast-forward merge requestsFor a linear Git history and a way to accept merge requests without creating merge commits
Find the merge request that introduced a changeWhen viewing the commit details page, GitLab will link to the merge request(s) containing that commit.
Ignore whitespace changes in Merge Request diff viewHide whitespace changes from the diff view for a to focus on more important changes.
Incrementally expand merge request diffsView the content directly above or below a change, to better understand the context of that change.
Live preview with Review AppsLive preview the changes when Review Apps are configured for your project
Merge request diff file navigationQuickly jump to any changed file within the diff view.
Merge requests versionsSelect and compare the different versions of merge request diffs
Merge when pipeline succeedsSet a merge request that looks ready to merge to merge automatically when CI pipeline succeeds.
Perform a Review Start a review in order to create multiple comments on a diff and publish them once you’re ready.
Pipeline status in merge requestsIf using GitLab CI/CD, see pre and post-merge pipelines information, and which deployments are in progress.
Post-merge pipeline statusWhen a merge request is merged, see the post-merge pipeline status of the branch the merge request was merged into.
Resolve conflictsGitLab can provide the option to resolve certain merge request conflicts in the GitLab UI.
Revert changesRevert changes from any commit from within a merge request.
Semi-linear history merge requestsEnable semi-linear history merge requests as another security layer to guarantee the pipeline is passing in the target branch
Suggest changesAdd suggestions to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI.
Time TrackingAdd a time estimation and the time spent with that merge request.
View changes between file versionsView what will be changed when a merge request is merged.
View group merge requestsList and view the merge requests within a group.
View project merge requestsList and view the merge requests within a project.

Testing and reports in merge requests

GitLab has the ability to test the changes included in a merge request, and can display or link to useful information directly in the merge request page:

FeatureDescription
Browser Performance Testing Quickly determine the performance impact of pending code changes.
Code Quality Analyze your source code quality using the Code Climate analyzer and show the Code Climate report right in the merge request widget area.
Display arbitrary job artifactsConfigure CI pipelines with the artifacts:expose_as parameter to directly link to selected artifacts in merge requests.
GitLab CI/CDBuild, test, and deploy your code in a per-branch basis with built-in CI/CD.
JUnit test reportsConfigure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log.
Metrics Reports Display the Metrics Report on the merge request so that it’s fast and easy to identify changes to important metrics.
Multi-Project pipelines When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies.
Pipelines for merge requestsCustomize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs.
Pipeline GraphsView the status of pipelines within the merge request, including the deployment process.

Security Reports

In addition to the reports listed above, GitLab can do many types of Security reports, generated by scanning and reporting any vulnerabilities found in your project:

FeatureDescription
Container ScanningAnalyze your Docker images for known vulnerabilities.
Dynamic Application Security Testing (DAST)Analyze your running web applications for known vulnerabilities.
Dependency ScanningAnalyze your dependencies for known vulnerabilities.
License ComplianceManage the licenses of your dependencies.
Static Application Security Testing (SAST)Analyze your source code for known vulnerabilities.

Authorization for merge requests

There are two main ways to have a merge request flow with GitLab:

  1. Working with protected branches in a single repository
  2. Working with forks of an authoritative project

Learn more about the authorization for merge requests.