Merge Request

What Is a Merge Request?

A merge request (commonly abbreviated as MR) is GitLab’s mechanism for proposing, reviewing, and approving code changes before they are merged into a target branch. Functionally, a merge request is identical to a pull request on GitHub or Bitbucket — it creates a dedicated space where developers can examine a diff, leave inline comments, run automated checks, and approve or reject changes. The difference is purely terminological and reflects GitLab’s design philosophy.

GitLab chose the term “merge request” because it describes the action from the author’s perspective: the developer is requesting that their branch be merged into the target. GitHub’s “pull request” describes the same action from the maintainer’s perspective: the maintainer is being asked to pull changes from a contributor’s fork. Both terms refer to the same workflow, and developers who switch between platforms regularly treat them as interchangeable.

Despite the naming difference, GitLab’s merge request implementation includes several features that distinguish it from its counterparts on other platforms. GitLab tightly couples merge requests with its built-in CI/CD system, offers native merge trains for managing concurrent merges, and provides approval rules that can require sign-off from specific teams or individuals before a merge is permitted.

How It Works

The merge request workflow in GitLab begins when a developer pushes a feature branch and creates an MR through the GitLab UI or CLI. GitLab automatically detects the branch and offers to create a merge request when the developer visits the project page after pushing.

# Push a feature branch to GitLab
git checkout -b feature/improve-search
git add .
git commit -m "Improve search indexing performance"
git push origin feature/improve-search

# GitLab CLI: create a merge request
glab mr create \
  --title "Improve search indexing performance" \
  --description "Optimizes the full-text search indexer by batching writes. Reduces indexing time by 40%." \
  --target-branch main \
  --reviewer @alice,@bob

Once the MR is opened, GitLab triggers the project’s CI/CD pipeline as defined in .gitlab-ci.yml. This pipeline typically runs unit tests, integration tests, linting, security scanning, and any other automated checks the team has configured:

# .gitlab-ci.yml — pipeline triggered on merge requests
stages:
  - test
  - lint
  - security

unit_tests:
  stage: test
  script:
    - npm ci
    - npm test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

eslint:
  stage: lint
  script:
    - npm ci
    - npm run lint
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

sast:
  stage: security
  template: Security/SAST.gitlab-ci.yml
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

GitLab displays pipeline results directly on the merge request page, giving reviewers immediate visibility into whether the changes pass all automated checks. Reviewers examine the diff, leave comments, and approve or request changes. GitLab supports configurable approval rules — for example, requiring at least two approvals, or requiring approval from a specific team for changes to sensitive directories.

One feature unique to GitLab is merge trains. When multiple merge requests target the same branch, a merge train queues them and tests each one on top of the previous MR’s changes. This ensures that the target branch never breaks due to conflicting concurrent merges, eliminating the “it worked on my branch” problem that plagues teams merging frequently to a shared mainline.

Why It Matters

Merge requests are central to GitLab’s DevSecOps platform strategy. Because GitLab integrates source control, CI/CD, security scanning, and deployment into a single application, the merge request becomes the single point of coordination for the entire software delivery lifecycle. A developer can open an MR, see test results, review security scan findings, check deployment previews, and get team approval — all without leaving GitLab.

This integration reduces context-switching and eliminates the need to stitch together separate tools for version control, CI, security, and project management. For teams that standardize on GitLab, the merge request is the primary artifact around which all development activity revolves.

Merge requests also provide traceability for compliance-sensitive environments. GitLab’s audit log records who created the MR, who approved it, which pipeline ran, and when the merge occurred. Organizations in regulated industries rely on this audit trail to demonstrate that every production change followed an approved review and testing process.

Best Practices

• Use merge request templates. GitLab supports description templates that pre-populate the MR body with sections for summary, testing instructions, and a checklist. Templates ensure consistency and remind authors to include essential context.
• Configure approval rules thoughtfully. Require approval from code owners for sensitive paths, but avoid requiring so many approvals that MRs stall in the queue. Two approvals is a common and effective threshold.
• Enable merge trains for high-traffic branches. If your team merges multiple MRs to main per day, merge trains prevent broken builds caused by incompatible concurrent changes.
• Link MRs to issues. Use GitLab’s Closes #123 syntax in the MR description to automatically close the related issue when the MR is merged. This keeps project tracking in sync with code changes.
• Set merge request size guidelines. Establish a team norm — such as a maximum of 400 changed lines — and use GitLab’s analytics dashboards to monitor compliance over time.

Common Mistakes

• Ignoring pipeline failures. GitLab makes it easy to override a failed pipeline and merge anyway. This practice erodes trust in the CI system and allows broken code to reach production. Treat pipeline failures as blockers, not suggestions.
• Skipping the description. An MR with no description forces reviewers to reverse-engineer the intent of the change from the diff alone. Always explain what changed, why it changed, and how to verify it.
• Letting MRs go stale. A merge request that sits open for weeks accumulates merge conflicts, drifts from the target branch, and becomes progressively harder to review. If an MR cannot be completed promptly, close it and reopen a fresh one when the work resumes.