Merge Request (MR): 개념, 생성 방법 및 리뷰 프로세스

Merge Request (MR)이란?

Merge Request (MR) — 한 Git 브랜치에서 다른 브랜치로 변경 사항을 통합하기 위한 요청으로, 코드 리뷰 및 자동 검사 프로세스를 시작합니다. 콘솔을 통한 직접 병합과 달리 MR은 공식적인 절차를 만듭니다. 개발자가 변경 사항을 설명하고, 리뷰어를 지정하고, CI/CD를 시작하고, 변경 사항이 적용되기 전에 피드백을 받습니다. 이는 GitLab의 핵심 요소이지만 GitHub의 동등한 메커니즘은 Pull Request (PR)라고 합니다.

GitLab Documentation, 2026에 따르면, GitLab에서 연간 8천만 개 이상의 Merge Requests가 생성됩니다. 각 MR에는 네 가지 주요 구성 요소가 있습니다. 변경 컨텍스트가 포함된 설명, 커밋 목록, 코드 차이(diff), 논의(토론 스레드)입니다. 이러한 요소 중 하나라도 없으면 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)을 사용합니다. Gerrit의 Change Request (CR)도 유사합니다. 세 가지 모두 코드 리뷰를 통해 변경 사항을 통합하기 위한 요청이라는 동일한 프로세스를 나타냅니다. 용어 선택은 프로젝트에서 사용하는 플랫폼에만 따라 달라집니다.

# 변경 사항이 포함된 브랜치 생성
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# GitLab/GitHub UI 또는 CLI를 통해 MR을 생성할 수 있습니다:
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR vs PR: GitLab과 GitHub의 차이점

GitLab의 Merge Request과 GitHub의 Pull Request는 기능적으로 동일한 메커니즘이며 이름만 다릅니다. 차이점은 역사에 기인합니다. GitLab은 원래 GitHub의 Self-Hosted 대안으로 자리 잡았으며 병합 프로세스에 “merge request”라는 용어를 선택했습니다. 먼저 시작된 GitHub는 메인 브랜치로 변경 사항을 “가져오기”(pull) 위한 요청으로 “pull request”를 사용했습니다.

GitHub Docs, 2024에 따르면, 두 도구 모두 동일한 기능 세트를 지원합니다. Markdown 설명, 리뷰어 지정, 특정 코드 줄에 대한 댓글, 확인 상태 및 조건 충족 시 자동 병합입니다. 차이점은 인터페이스와 추가 기능에 관한 것입니다.

Merge Request 생성 방법: 단계별 가이드

Merge Request (MR) 생성은 변경 사항이 포함된 브랜치를 원격 저장소에 게시하는 것으로 시작됩니다. GitLab 또는 GitHub에 푸시하면 인터페이스에 “Create Merge Request” 또는 “Compare & Pull Request” 버튼이 나타납니다. 개발자가 설명을 작성하고, 대상 브랜치(일반적으로 develop 또는 main)를 지정하고, 리뷰어를 할당하고, 레이블을 첨부합니다.

GitLab Documentation, 2025에 따르면, 표준 MR에는 최대 72자의 제목, 템플릿이 포함된 설명 및 이슈 링크가 포함됩니다. 설명은 어떤 작업이 수행되었는지, 왜, 어떻게 테스트되었는지에 대한 질문에 답변해야 합니다. GitLab은 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 상태로 전환됩니다. 코드 리뷰가 시작되고 CI/CD 파이프라인이 시작됩니다.

GitLab Docs, 2024에 따르면, Opened 상태에서 리뷰어는 diff를 검사하고, 댓글을 남기고, Resolve Threads를 통해 변경을 요청합니다. 모든 스레드가 해결되고 CI/CD가 성공하면 책임 개발자가 Approve를 설정합니다. 그런 다음 Merge 버튼을 사용하여 병합하거나 자동 병합(Auto-merge)을 기다릴 수 있습니다.

GitLab은 세 가지 최종 상태 옵션을 지원합니다. Merged(성공적으로 병합됨), Closed(기능 포기 등으로 병합 없이 종료), Reopened(종료 후 재개)입니다. 각 상태는 감사를 위해 MR 활동 타임라인에 기록됩니다.

자동 상태 및 트리거

GitLab은 이벤트에 따라 Merge Request 상태를 자동으로 업데이트합니다. 새 커밋 푸시 시 Approvals가 재설정되고, CI 파이프라인 성공 시 Pipeline passed, 실패 시 Pipeline failed(병합 차단)가 됩니다. Auto-merge를 구성하면 CI 성공 및 모든 필수 승인 후 MR이 자동 병합됩니다.

• Draft — 초안, CI 실행되지만 병합 차단됨
• Opened — 리뷰 준비 완료, 리뷰어 지정됨, 파이프라인 활성
• Approved — 필요한 승인 수 획득
• Merged — 대상 브랜치에 변경 사항 병합됨
• Closed — 병합 없이 종료됨

Merge Request의 코드 리뷰 규칙

Merge Request (MR)의 코드 리뷰는 대부분의 상업용 프로젝트에서 필수 단계입니다. SmartBear, 2023 연구에 따르면, MR을 통한 코드 리뷰는 결함 수를 30–60% 줄이고 신규 개발자의 온보딩을 가속화합니다. 기본 규칙은 각 MR이 코드 작성에 참여하지 않은 최소 한 명, 이상적으로는 두 명의 개발자가 검토해야 한다는 것입니다.

MR 검토에는 다섯 가지 기준이 포함됩니다. 논리적 정확성, 코드 스타일 준수, 테스트 커버리지, 보안 및 성능입니다. GitLab에서 Required Approvals를 구성하여 병합 전 필수 승인 수를 지정할 수 있습니다(예: main은 2개 승인, develop은 1개 승인).

MR에서의 논의는 스레드에서 진행됩니다. 특정 코드 줄에 대한 댓글입니다. 각 스레드는 병합 전에 해결되어야 합니다. 리뷰 속도를 높이기 위해 MR 크기를 200–400줄의 변경으로 제한하는 것이 좋습니다. Google Research(2022)에 따르면 400줄을 초과하는 MR은 30% 덜 효과적으로 검토됩니다.

Merge Request의 CI/CD 파이프라인

Merge Request (MR)이 생성되면 CI/CD 파이프라인이 자동으로 시작됩니다. GitLab에서는 .gitlab-ci.yml 파일을 통해, GitHub에서는 GitHub Actions 워크플로를 통해 이루어집니다. 파이프라인에는 프로젝트 빌드, 단위 테스트, 린터, 정적 분석(SAST) 및 코드 커버리지 확인이 포함됩니다.

GitLab Blog, 2024에 따르면, 파이프라인 상태가 MR에 직접 표시됩니다. 녹색 체크표시(passed), 빨간색 X(failed), 노란색 원(running)입니다. 파이프라인이 실패하면 GitLab이 수정될 때까지 Merge 버튼을 차단합니다. 설정에서 “Merge when pipeline succeeds”를 활성화하면 파이프라인 성공 후 자동 병합됩니다.

# .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은 별도의 병합 커밋을 생성하여 전체 기능 브랜치 기록을 보존합니다. Squash는 모든 브랜치 커밋을 대상 브랜치의 단일 커밋으로 결합합니다. Fast-Forward는 병합 커밋 없이 커밋을 선형으로 적용합니다.

GitLab Docs, 2025에 따르면, 커밋 밀도가 높은 프로젝트(하나의 기능 브랜치에 20개 이상의 커밋)에서는 Squash가 선호됩니다. Fast-Forward는 Trunk-Based Development에 필수입니다. Merge Commit은 Git Flow에서 브랜칭 의미를 보존하기 위해 사용됩니다.

• Merge Commit — 기록 보존, 병합 커밋 생성, Git Flow에 적합
• Squash — 모든 커밋을 하나로 결합, 깔끔한 기록, 중간 커밋 손실
• Fast-Forward — 병합 커밋 없는 선형 기록, TBD에서 필수

모범 사례: 좋은 MR 작성 방법

품질 높은 Merge Request (MR)은 리뷰 시간과 오류 수를 줄입니다. 첫 번째 규칙은 하나의 MR이 하나의 작업을 해결한다는 것입니다. 변경 사항이 여러 관련 없는 기능에 영향을 미치는 경우 별도의 MR로 분할해야 합니다. 둘째, MR 제목은 정보를 제공해야 합니다. “Fix stuff”나 “Update code” 대신 “Add OAuth2 authentication with Google provider”와 같이 작성합니다.

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은 .gitlab/merge_request_templates/ 파일을 통해 Merge Request 템플릿을 지원합니다. 템플릿에는 수행한 작업, 테스트 방법, 관련 작업 및 체크리스트 섹션이 포함됩니다. 템플릿을 사용하면 MR 생성이 빨라지고 개발자가 중요한 정보를 포함하는 것을 잊지 않도록 보장합니다. MR 설명에는 병합 시 자동 작업 종료를 위해 관련 이슈(Closes #N)를 지정해야 합니다.