Merge Request (MR): چیست، چگونه ایجاد کنیم و فرآیند بازبینی

Merge Request (MR) چیست؟

Merge Request (MR) — درخواست ادغام تغییرات از یک شاخه Git به شاخه دیگر که فرآیند بازبینی کد و بررسی خودکار را آغاز می‌کند. برخلاف ادغام مستقیم از طریق کنسول، MR یک رویه رسمی ایجاد می‌کند: توسعه‌دهنده تغییرات را توصیف می‌کند، بازبین‌ها را تعیین می‌کند، CI/CD را راه‌اندازی می‌کند و قبل از اعمال تغییرات بازخورد دریافت می‌کند. این عنصر کلیدی GitLab است، اما مکانیزم مشابه در GitHub Pull Request (PR) نامیده می‌شود.

به گزارش GitLab Documentation, 2026، در GitLab سالانه بیش از 80 میلیون Merge Request ایجاد می‌شود. هر MR شامل چهار مؤلفه اصلی است: توضیحات (description) با زمینه تغییرات، لیست commitها (commits)، تفاوت کد (diff) و بحث (discussion thread). بدون یکی از این عناصر، MR ناقص محسوب می‌شود.

Merge Request (MR) سه وظیفه را حل می‌کند: از تغییرات مستقیم در شاخه‌های محافظت‌شده (main, develop) جلوگیری می‌کند، کنترل کیفیت را از طریق بازبینی تضمین می‌کند و تاریخچه بحث‌ها را برای توسعه‌دهندگان آینده حفظ می‌کند. در GitLab وضعیت MR در رابط با نشانه‌های رنگی نمایش داده می‌شود: خاکستری برای Draft، نارنجی برای در انتظار، سبز برای Approved، بنفش برای Merged و قرمز برای Closed.

اصطلاحات: MR، PR و CR

در پلتفرم‌های مختلف Git، Merge Request به طور متفاوت نامیده می‌شود. GitLab از «Merge Request» (MR)، GitHub از «Pull Request» (PR) استفاده می‌کند. مشابه — Change Request (CR) در Gerrit. هر سه به یک فرآیند اشاره دارند: درخواست ادغام تغییرات از طریق بازبینی کد. انتخاب اصطلاح فقط به پلتفرم مورد استفاده در پروژه بستگی دارد.

# ایجاد شاخه با تغییرات
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# MR را می‌توان از طریق UI GitLab/GitHub یا CLI ایجاد کرد:
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR در مقابل PR: تفاوت بین GitLab و GitHub

Merge Request در GitLab و Pull Request در GitHub — مکانیزم‌هایی با عملکرد یکسان و نام‌های متفاوت هستند. تفاوت به تاریخچه برمی‌گردد: GitLab در ابتدا به عنوان جایگزین Self-Hosted برای GitHub positioning شد و اصطلاح «merge request» را برای فرآیند ادغام انتخاب کرد. GitHub که زودتر راه‌اندازی شده بود، از «pull request» — درخواست «کشیدن» (pull) تغییرات به شاخه اصلی استفاده کرد.

به گزارش GitHub Docs, 2024، هر دو ابزار از مجموعه یکسانی از قابلیت‌ها پشتیبانی می‌کنند: توضیحات با Markdown، تعیین بازبین‌ها، نظر دادن روی خطوط خاص کد، وضعیت‌های بررسی و ادغام خودکار در صورت برآورده شدن شرایط. تفاوت‌ها به رابط و قابلیت‌های اضافی مربوط می‌شود.

چگونه Merge Request ایجاد کنیم: راهنمای گام به گام

ایجاد Merge Request (MR) با انتشار شاخه حاوی تغییرات در مخزن راه دور آغاز می‌شود. پس از push به GitLab یا GitHub، دکمه «Create Merge Request» یا «Compare & Pull Request» در رابط ظاهر می‌شود. توسعه‌دهنده توضیحات را پر می‌کند، شاخه هدف (معمولاً develop یا main) را مشخص می‌کند، بازبین‌ها را تعیین کرده و برچسب‌ها (labels) را اضافه می‌کند.

به گزارش GitLab Documentation, 2025، یک MR استاندارد شامل عنوان تا 72 کاراکتر، توضیحات با الگو (template) و پیوند به وظیفه (issue) است. توضیحات باید به سؤالات پاسخ دهد: چه کاری انجام شده، چرا، چگونه تست شده است. GitLab از بستن خودکار issue در هنگام ادغام از طریق کلمات کلیدی Closes, Fixes, Resolves پشتیبانی می‌کند.

# نمونه الگوی .gitlab/merge_request_templates/default.md
## What does this MR do?

[توضیح مختصر تغییرات: چه و چرا]

## How to test

1. اجرای ./gradlew test
2. بررسی LoginActivity با توکن تستی
3. اطمینان از عدم وجود regression در AuthManager

## Related issues

Closes #142

چرخه حیات MR: از Draft تا Merged

Merge Request (MR) پنج وضعیت را در GitLab طی می‌کند. اولین — Draft (پیش‌نویس)، با پیشوند «Draft:» در عنوان مشخص می‌شود و ادغام را مسدود می‌کند. پس از آماده شدن، توسعه‌دهنده Draft را حذف می‌کند و MR به وضعیت Opened می‌رود — بازبینی کد آغاز شده و pipeline CI/CD راه‌اندازی می‌شود.

به گزارش GitLab Docs, 2024، در وضعیت Opened بازبین‌ها diff را بررسی می‌کنند، نظر می‌دهند و از طریق Resolve Threads تغییرات درخواست می‌کنند. وقتی همه موضوعات بسته شدند و CI/CD با موفقیت گذشت، توسعه‌دهنده مسئول Approve را قرار می‌دهد. پس از آن MR را می‌توان با دکمه Merge ادغام کرد یا منتظر ادغام خودکار (Auto-merge) شد.

GitLab از سه variant وضعیت نهایی پشتیبانی می‌کند: Merged (با موفقیت ادغام شده)، Closed (بدون ادغام بسته شده، مثلاً در صورت انصراف از ویژگی) و Reopened (بازگشایی مجدد پس از بسته شدن). هر وضعیت در Activity Timeline MR برای ممیزی ثبت می‌شود.

وضعیت‌های خودکار و محرک‌ها

GitLab هنگام وقوع رویدادها وضعیت Merge Request را به طور خودکار به‌روزرسانی می‌کند: با push commitهای جدید، Approvals بازنشانی می‌شوند، با CI pipeline موفق وضعیت Pipeline passed می‌شود، با خطا — Pipeline failed (ادغام مسدود می‌شود). می‌توان Auto-merge را پیکربندی کرد: MR پس از CI موفق و دریافت همه تأییدهای مورد نیاز به طور خودکار ادغام می‌شود.

• Draft — پیش‌نویس، CI راه‌اندازی می‌شود اما ادغام مسدود است
• Opened — آماده بازبینی، بازبین‌ها تعیین شده‌اند، pipeline فعال است
• Approved — تعداد تأییدهای مورد نیاز دریافت شده است
• Merged — تغییرات در شاخه هدف ادغام شده‌اند
• Closed — بدون ادغام بسته شده است

قوانین بازبینی کد در Merge Request

بازبینی کد در Merge Request (MR) — مرحله اجباری در اکثر پروژه‌های تجاری. به گزارش تحقیق SmartBear, 2023، بازبینی کد با MR تعداد نقص‌ها را 30–60% کاهش می‌دهد و آموزش توسعه‌دهندگان جدید را تسریع می‌کند. قانون اصلی — هر MR حداقل توسط یک، و بهتر دو توسعه‌دهنده که در نوشتن کد شرکت نداشته‌اند بررسی می‌شود.

بررسی MR شامل پنج معیار است: صحت منطق، تطابق با سبک کد، پوشش تست، امنیت و عملکرد. در GitLab می‌توان Required Approvals — تعداد تأییدهای اجباری قبل از ادغام را پیکربندی کرد، مثلاً 2 تأیید برای main و 1 برای develop.

بحث در MR در Threads — نظرات روی خطوط خاص کد انجام می‌شود. هر موضوع باید قبل از ادغام resolved (بسته) شود. برای تسریع بازبینی، توصیه می‌شود اندازه MR را محدود کنید: 200–400 خط تغییر. طبق داده‌های Google Research (2022)، MRهای بزرگتر از 400 خط با 30% کارایی کمتر بررسی می‌شوند.

Pipeline CI/CD در Merge Request

هنگام ایجاد Merge Request (MR)، pipeline CI/CD به طور خودکار راه‌اندازی می‌شود. در GitLab این کار از طریق فایل .gitlab-ci.yml، در GitHub — از طریق GitHub Actions workflow انجام می‌شود. Pipeline شامل ساخت پروژه (build)، اجرای تست‌های واحد (unit tests)، linterها (lint)، تحلیل ایستا (SAST) و بررسی پوشش کد است.

به گزارش GitLab Blog, 2024، وضعیت pipeline مستقیماً در MR نمایش داده می‌شود: علامت سبز (passed)، ضربدر قرمز (failed) یا دایره زرد (running). اگر pipeline شکست بخورد، GitLab دکمه Merge را تا رفع مشکل مسدود می‌کند. در تنظیمات می‌توان «Merge when pipeline succeeds» — ادغام خودکار پس از pipeline موفق را فعال کرد.

# .gitlab-ci.yml — نمونه برای پروژه Android
test:
  stage: test
  script:
    - ./gradlew ktlintCheck
    - ./gradlew testDebugUnitTest
  only:
    - merge_requests

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

روش‌های ادغام: Squash, Merge Commit, Fast-Forward

GitLab و GitHub سه روش ادغام برای Merge Request ارائه می‌دهند. انتخاب بستگی به سیاست تیم و خلوص تاریخ مورد نیاز دارد. Merge Commit — یک commit ادغام جداگانه ایجاد می‌کند و تمام تاریخ شاخه ویژگی را حفظ می‌کند. Squash — تمام commitهای شاخه را در یک commit در شاخه هدف ادغام می‌کند. Fast-Forward — commitها را بدون commit ادغام به صورت خطی اعمال می‌کند.

به گزارش GitLab Docs, 2025، Squash در پروژه‌های با تراکم بالای commit (20+ commit در یک شاخه ویژگی) ترجیح داده می‌شود. Fast-Forward برای Trunk-Based Development اجباری است. Merge Commit در Git Flow برای حفظ معناشناسی شاخه‌بندی استفاده می‌شود.

• Merge Commit — تاریخ را حفظ می‌کند، commit ادغام ایجاد می‌کند، مناسب برای Git Flow
• Squash — همه commitها را در یکی ادغام می‌کند، تاریخ تمیز، commitهای میانی از دست می‌روند
• Fast-Forward — تاریخ خطی بدون commit ادغام، اجباری در TBD

بهترین روش‌ها: چگونه یک MR خوب بنویسیم

Merge Request (MR) با کیفیت زمان بازبینی را کاهش می‌دهد و تعداد خطاها را کم می‌کند. قانون اول — یک MR یک وظیفه را حل می‌کند. اگر تغییرات به چندین ویژگی نامرتبط مربوط می‌شود، باید به MRهای جداگانه تقسیم شوند. دوم — عنوان MR باید informative باشد: «Add OAuth2 authentication with Google provider» به جای «Fix stuff» یا «Update code».

به گزارش Google Engineering Practices, 2024، یک MR خوب شامل توضیحات زمینه است: چرا تغییرات ضروری هستند، چگونه تست شده‌اند، چه ریسک‌هایی وجود دارد. اندازه MR نباید از 400 خط تغییر تجاوز کند. اگر حجم بیشتر است — وظیفه باید به زیروظایف تقسیم شود. برای مستندات و تست‌ها استثناها مجاز هستند، اما با توضیح.

Merge Request (MR) باید شامل تست‌های خودکار برای قابلیت جدید باشد. در GitLab می‌توان سیاست Coverage Check را پیکربندی کرد — اگر پوشش کد زیر آستانه (مثلاً 80%) بیفتد، MR به طور خودکار مسدود می‌شود. این تضمین می‌کند که قابلیت جدید کیفیت کلی پروژه را کاهش نمی‌دهد.

• یک MR — یک وظیفه: تغییرات بزرگ را به چند MR کوچک تقسیم کنید
• توضیحات با الگو: برای یکنواختی از .gitlab/merge_request_templates استفاده کنید
• اندازه تا 400 خط: MRهای بزرگ کندتر و با خطاهای بیشتر بررسی می‌شوند
• تست‌ها اجباری: ویژگی‌های جدید باید با تست‌های واحد پوشش داده شوند

الگوهای توضیحات MR

GitLab از الگوهای Merge Request از طریق فایل‌های .gitlab/merge_request_templates/ پشتیبانی می‌کند. الگو شامل بخش‌هایی است: چه کاری انجام شده، چگونه تست کنیم، وظایف مرتبط و چک‌لیست. استفاده از الگوها ایجاد MR را تسریع می‌کند و تضمین می‌کند که توسعه‌دهندگان اطلاعات مهم را فراموش نمی‌کنند. در توضیحات MR حتماً issue مرتبط (Closes #N) برای بستن خودکار وظایف در هنگام ادغام ذکر می‌شود.