Merge Request (MR): What It Is, How to Create, and the Review Process

What is a Merge Request (MR)?

Merge Request (MR) — a request to integrate changes from one Git branch into another, which initiates the process of code review and automated checks. Unlike direct merging via the console, MR creates a formal procedure: the developer describes the changes, assigns reviewers, launches CI/CD, and receives feedback before the changes are applied. This is a key element of GitLab, but the equivalent mechanism in GitHub is called Pull Request (PR).

According to GitLab Documentation, 2026, more than 80 million Merge Requests are created in GitLab annually. Each MR contains four main components: a description with change context, a list of commits, the code difference (diff), and discussion (discussion thread). Without one of these elements, the MR is considered incomplete.

Merge Request (MR) solves three tasks: prevents direct changes to protected branches (main, develop), provides quality control through review, and preserves discussion history for future developers. In GitLab, the MR status is displayed in the interface with color indicators: gray for Draft, orange for pending, green for Approved, purple for Merged, and red for Closed.

Terminology: MR, PR, and CR

In different Git platforms, Merge Request is called differently. GitLab uses “Merge Request” (MR), GitHub uses “Pull Request” (PR). The analogy is Change Request (CR) in Gerrit. All three denote the same process: a request to integrate changes through code review. The choice of term depends only on the platform used in the project.

# Create a branch with changes
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# You can create an MR via GitLab/GitHub UI or CLI:
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR vs PR: What’s the Difference Between GitLab and GitHub

Merge Request in GitLab and Pull Request in GitHub are functionally identical mechanisms with different names. The difference is due to history: GitLab originally positioned itself as a Self-Hosted alternative to GitHub and chose the term “merge request” for the merging process. GitHub, launched earlier, used “pull request” — a request to “pull” changes into the main branch.

According to GitHub Docs, 2024, both tools support the same set of features: Markdown description, reviewer assignment, commenting on specific lines of code, check statuses, and automatic merging when conditions are met. Differences relate to the interface and additional capabilities.

How to Create a Merge Request: Step-by-Step Guide

Creating a Merge Request (MR) starts with publishing a branch with changes to the remote repository. After pushing to GitLab or GitHub, the interface shows a “Create Merge Request” or “Compare & Pull Request” button. The developer fills in the description, specifies the target branch (usually develop or main), assigns reviewers, and attaches labels.

According to GitLab Documentation, 2025, a standard MR contains a title of up to 72 characters, a description with a template, and a link to the issue. The description should answer the questions: what was done, why, how it was tested. GitLab supports auto-closing issues upon merge using keywords Closes, Fixes, Resolves.

# Example of .gitlab/merge_request_templates/default.md template
## What does this MR do?

[Brief description of the changes: what and why]

## How to test

1. Run ./gradlew test
2. Check LoginActivity with a test token
3. Make sure there is no regression in AuthManager

## Related issues

Closes #142

MR Lifecycle: From Draft to Merged

Merge Request (MR) goes through five statuses in GitLab. The first is Draft (draft), marked with the prefix “Draft:” in the title, which blocks merging. When ready, the developer removes Draft, and the MR transitions to Opened status — code review begins and the CI/CD pipeline starts.

According to GitLab Docs, 2024, in Opened status, reviewers examine the diff, leave comments, and request changes through Resolve Threads. When all threads are resolved and CI/CD passes successfully, the responsible developer sets Approve. After that, the MR can be merged using the Merge button, or automatic merging (Auto-merge) can be awaited.

GitLab supports three final status options: Merged (successfully merged), Closed (closed without merging, e.g., when abandoning a feature), and Reopened (reopening after closure). Each status is logged in the MR Activity Timeline for auditing.

Automatic Statuses and Triggers

GitLab automatically updates the Merge Request status upon events: pushing new commits resets Approvals, upon successful CI pipeline the status becomes Pipeline passed, upon failure — Pipeline failed (merge is blocked). Auto-merge can be configured: the MR is automatically merged after successful CI and receiving all required approvals.

• Draft — draft, CI runs but merge is blocked
• Opened — ready for review, reviewers assigned, pipeline active
• Approved — required number of approvals received
• Merged — changes merged into target branch
• Closed — closed without merging

Code Review Rules in Merge Request

Code review in Merge Request (MR) is a mandatory stage in most commercial projects. According to SmartBear, 2023, code review with MR reduces the number of defects by 30–60% and accelerates onboarding of new developers. The main rule is that each MR is checked by at least one, preferably two developers who did not participate in writing the code.

MR review includes five criteria: logical correctness, code style compliance, test coverage, security, and performance. In GitLab, Required Approvals can be configured — the mandatory number of approvals before merging, for example, 2 approvals for main and 1 for develop.

Discussion in MR is conducted in Threads — comments on specific code lines. Each thread must be resolved before merging. To speed up reviews, it’s recommended to limit MR size: 200–400 lines of changes. According to Google Research (2022), MRs larger than 400 lines are reviewed 30% less effectively.

CI/CD Pipeline in Merge Request

When a Merge Request (MR) is created, the CI/CD pipeline automatically starts. In GitLab this happens through the .gitlab-ci.yml file, in GitHub through GitHub Actions workflow. The pipeline includes project build, unit tests, linters, static analysis (SAST), and code coverage check.

According to GitLab Blog, 2024, the pipeline status is displayed directly in the MR: green checkmark (passed), red cross (failed), or yellow circle (running). If the pipeline fails, GitLab blocks the Merge button until fixed. In settings, “Merge when pipeline succeeds” can be enabled — automatic merge after a successful pipeline.

# .gitlab-ci.yml — example for an Android project
test:
  stage: test
  script:
    - ./gradlew ktlintCheck
    - ./gradlew testDebugUnitTest
  only:
    - merge_requests

build:
  stage: build
  script:
    - ./gradlew assembleDebug
  only:
    - merge_requests

Merge Methods: Squash, Merge Commit, Fast-Forward

GitLab and GitHub offer three merge methods for Merge Request. The choice depends on team policy and desired history cleanliness. Merge Commit creates a separate merge commit, preserving the entire feature branch history. Squash combines all branch commits into a single commit on the target branch. Fast-Forward applies commits linearly without a merge commit.

According to GitLab Docs, 2025, Squash is preferred for projects with high commit density (20+ commits in one feature branch). Fast-Forward is mandatory for Trunk-Based Development. Merge Commit is used in Git Flow to preserve branching semantics.

• Merge Commit — preserves history, creates a merge commit, suitable for Git Flow
• Squash — combines all commits into one, clean history, loses intermediate commits
• Fast-Forward — linear history without a merge commit, mandatory in TBD

Best Practices: How to Write a Good MR

A quality Merge Request (MR) reduces review time and the number of errors. The first rule is one MR solves one task. If changes affect multiple unrelated features, they should be split into separate MRs. Second, the MR title should be informative: “Add OAuth2 authentication with Google provider” instead of “Fix stuff” or “Update code”.

According to Google Engineering Practices, 2024, a good MR contains a context description: why the changes are necessary, how they were tested, and what risks exist. The MR size should not exceed 400 lines of changes. If the volume is larger, the task needs to be decomposed into subtasks. For documentation and tests, exceptions are acceptable but with explanation.

Merge Request (MR) should include automated tests for new functionality. In GitLab, Coverage Check policy can be configured — the MR is automatically blocked if code coverage drops below a threshold (e.g., 80%). This ensures that new functionality does not reduce overall project quality.

• One MR — one task: decompose large changes into several small MRs
• Description with template: use .gitlab/merge_request_templates for consistency
• Size up to 400 lines: large MRs are reviewed slower and with more errors
• Tests are mandatory: new features must be covered by unit tests

MR Description Templates

GitLab supports Merge Request templates through .gitlab/merge_request_templates/ files. The template includes sections: what was done, how to test, related tasks, and checklist. Using templates speeds up MR creation and ensures developers don’t forget to include important information. In the MR description, related issues (Closes #N) must be specified for auto-closing tasks upon merge.