[Git] - Pull Request(PR) / Merge Request(MR) 작성법

개요

안녕하세요. 이번 시간에는 협업에서 가장 중요한 Pull Request(PR)와 Merge Request(MR) 작성법에 대해 알아보겠습니다. GitHub에서는 Pull Request, GitLab에서는 Merge Request라고 부르지만 기본 개념은 동일합니다. 혹시 이전 시간에 내용을 학습하고 오시지 못 하신 분들은 학습하고 오시는 걸 추천드리겠습니다.

 

[Git] - Clone vs Fork 차이점

 

- Pull Request란?

Pull Request(PR)는 내가 작성한 코드를 프로젝트의 메인 브랜치에 병합해달라고 요청하는 기능입니다. 단순히 코드를 합치는 것이 아니라, 코드 리뷰를 받고 팀원들과 소통하는 협업의 핵심 도구입니다.

PR의 목적

• 코드 리뷰를 통한 품질 향상
• 팀원들과의 코드 공유 및 토론
• 변경 사항에 대한 문서화
• 자동화된 테스트 실행
• 프로젝트의 히스토리 관리

GitHub vs GitLab 용어 비교

GitHubGitLab의미

Pull Request (PR)	Merge Request (MR)	병합 요청
Review	Approval	승인
Assignee	Assignee	담당자
Reviewer	Reviewer	리뷰어

💡 이 글에서는 GitHub 기준으로 설명하지만, GitLab도 동일한 방식으로 사용할 수 있습니다.

- PR 생성 전 준비사항

1. 브랜치 전략 이해하기

PR을 만들기 전에 팀의 브랜치 전략을 이해해야 합니다.

 

 

main (또는 master)
  ↑
  └─ develop
       ↑
       ├─ feature/login
       ├─ feature/user-profile
       └─ bugfix/header-issue

일반적으로 다음과 같은 브랜치 구조를 사용합니다:

브랜치용도예시

main/master	배포용 안정 브랜치	main
develop	개발용 통합 브랜치	develop
feature/*	새 기능 개발	feature/login
bugfix/*	버그 수정	bugfix/header-issue
hotfix/*	긴급 수정	hotfix/security-patch

2. 작업 브랜치 생성 및 작업

 

 

bash

# develop 브랜치로 이동
git checkout develop

# 최신 상태로 업데이트
git pull origin develop

# 새 브랜치 생성 및 이동
git checkout -b feature/user-authentication

# 작업 진행...
# 파일 수정, 추가 등

# 변경사항 확인
git status

# 스테이징
git add .

# 커밋 (의미있는 메시지 작성)
git commit -m "feat: 사용자 인증 기능 구현

- JWT 토큰 기반 인증 추가
- 로그인/로그아웃 API 구현
- 인증 미들웨어 추가"

# 원격 저장소에 푸시
git push origin feature/user-authentication

3. 커밋 정리하기

PR을 생성하기 전에 커밋을 깔끔하게 정리하는 것이 좋습니다.

 

 

bash

# 최근 3개 커밋 합치기
git rebase -i HEAD~3

# 에디터에서 pick을 squash로 변경
# pick abc1234 feat: 로그인 기능 추가
# squash def5678 fix: 로그인 버그 수정
# squash ghi9012 refactor: 코드 정리

# 강제 푸시 (주의: 이미 공유된 브랜치는 피하기)
git push origin feature/user-authentication --force

⚠️ 주의: 다른 사람과 공유하는 브랜치에서는 force push를 피하세요!

- GitHub에서 PR 생성하기

1. PR 생성 페이지 접근

GitHub 저장소에서 PR을 생성하는 방법은 여러 가지가 있습니다:

 

 

 

방법 1: 푸시 직후 노란색 배너 클릭

푸시 직후 저장소 페이지에 나타나는
"Compare & pull request" 버튼 클릭

 

방법 2: Pull requests 탭에서 생성

1. Pull requests 탭 클릭
2. "New pull request" 버튼 클릭
3. 브랜치 선택

 

방법 3: 브랜치에서 직접 생성

1. Code 탭의 브랜치 드롭다운 클릭
2. 원하는 브랜치 옆 PR 아이콘 클릭

 

2. 브랜치 선택

PR을 생성할 때 다음을 명확히 선택해야 합니다

 

base: develop  ← into (병합될 대상 브랜치)
compare: feature/user-authentication  ← from (내가 작업한 브랜치)

3. PR 제목 작성

좋은 PR 제목 예시:

✅ 좋은 예시:
- feat: 사용자 인증 기능 구현
- fix: 헤더 메뉴 모바일 반응형 버그 수정
- refactor: API 호출 로직을 React Query로 개선
- docs: API 문서에 인증 엔드포인트 추가

❌ 나쁜 예시:
- 작업 완료
- 수정
- Update
- 기능 추가

4. PR 설명 작성

PR 설명은 변경 사항을 명확히 전달하는 중요한 부분입니다.

기본 템플릿:

 

 

markdown

## 작업 내용
이 PR에서 무엇을 했는지 간단히 설명합니다.

## 변경 사항
- JWT 기반 인증 시스템 구현
- 로그인/로그아웃 API 엔드포인트 추가
- 인증 미들웨어 추가
- 로그인 페이지 UI 구현

## 테스트 방법
1. `npm install` 실행
2. `npm run dev` 로 서버 실행
3. `/login` 페이지 접속
4. test@example.com / password123 으로 로그인
5. 대시보드 페이지로 리다이렉트 확인

## 스크린샷 (필요시)
![로그인 화면](이미지_URL)

## 관련 이슈
- Closes #123
- Related to #456

## 체크리스트
- [x] 코드 작성 완료
- [x] 로컬 테스트 완료
- [x] 코드 리뷰 준비 완료
- [ ] 문서 업데이트 필요

실제 작성 예시:

 

 

markdown

## 작업 내용
사용자 인증 기능을 JWT 기반으로 구현했습니다.

## 변경 사항
### Backend
- `/api/auth/login` POST 엔드포인트 추가
- `/api/auth/logout` POST 엔드포인트 추가
- JWT 토큰 생성 및 검증 로직 구현
- 인증 미들웨어 (`authMiddleware.js`) 추가

### Frontend
- 로그인 페이지 UI 구현 (`/pages/Login.jsx`)
- 로그인 폼 유효성 검사 추가
- 토큰 저장 및 관리 (localStorage)
- Axios 인터셉터에 토큰 자동 포함

## 주요 기술 스택
- JWT (jsonwebtoken)
- bcrypt (비밀번호 암호화)
- React Hook Form (폼 관리)

## 테스트 방법
### 로컬 환경 설정
```bash
npm install
cp .env.example .env
# .env 파일에서 JWT_SECRET 설정
npm run dev
```

### 테스트 시나리오
1. http://localhost:3000/login 접속
2. 테스트 계정으로 로그인
   - Email: test@example.com
   - Password: password123
3. 로그인 성공 후 대시보드로 이동 확인
4. 로그아웃 버튼 클릭 후 로그인 페이지로 이동 확인
5. 인증 없이 /dashboard 접근 시 로그인 페이지로 리다이렉트 확인

## 관련 이슈
Closes #45

## 리뷰 요청 사항
- 보안 관련 부분 특히 신경써서 리뷰 부탁드립니다
- JWT 토큰 만료 시간이 적절한지 확인 부탁드립니다

- PR 옵션 설정

1. Reviewers (리뷰어) 지정

코드 리뷰를 받을 팀원을 지정합니다.

💡 팁:
- 해당 분야 전문가를 최소 1명 이상 지정
- 팀 규모에 따라 2-3명 정도가 적당
- 모든 팀원을 지정하면 책임이 분산될 수 있음

 

2. Assignees (담당자) 지정

PR의 책임자를 지정합니다. 보통 본인을 지정합니다.

3. Labels (레이블) 추가

PR의 성격을 표시합니다.

레이블의미예시

feature	새 기능	로그인 기능
bugfix	버그 수정	헤더 버그 수정
hotfix	긴급 수정	보안 패치
documentation	문서 작업	README 업데이트
refactoring	리팩토링	코드 정리
WIP	작업 중	Work In Progress
needs review	리뷰 필요	-

4. Milestone (마일스톤) 설정

특정 버전이나 목표와 연결합니다.

예시:
- v1.0.0 Release
- Q1 2024 Features
- Sprint 15

5. Projects 연결

프로젝트 보드와 연결하여 진행 상황을 추적합니다.

- 코드 리뷰 받기

1. 리뷰 요청 알림

리뷰어가 지정되면 자동으로 알림이 전송됩니다.

2. 리뷰 유형

GitHub에서 리뷰어가 남길 수 있는 피드백 유형:

유형의미아이콘

Comment	단순 의견	💬
Approve	승인 (머지 가능)	✅
Request changes	수정 요청 (머지 불가)	❌

3. 리뷰 코멘트에 응답하기

 

코멘트 확인:

1. PR 페이지의 "Files changed" 탭 확인
2. 각 코멘트 확인 및 응답
3. 필요시 추가 커밋으로 수정

응답 예시:

markdown

> 이 부분에서 에러 핸들링이 필요할 것 같습니다.

좋은 지적 감사합니다! try-catch 블록을 추가했습니다.
커밋: a1b2c3d

4. 수정 후 추가 커밋

 

bash

# 리뷰 반영하여 수정
git add .
git commit -m "review: 에러 핸들링 로직 추가"
git push origin feature/user-authentication

# 자동으로 PR에 반영됨

5. 리뷰 완료 후 대응

모든 리뷰가 Approve인 경우:

✅ 머지 준비 완료!

Request changes가 있는 경우:

❌ 요청사항 수정 후 다시 리뷰 요청
- "Re-request review" 버튼 클릭

- PR 머지하기

머지 전 체크리스트

 

markdown

- [ ] 모든 리뷰가 Approve 상태인가?
- [ ] CI/CD 테스트가 통과했는가?
- [ ] 충돌(Conflict)이 없는가?
- [ ] 최신 base 브랜치를 merge 했는가?
- [ ] 문서가 업데이트 되었는가?

머지 옵션 선택

GitHub에서는 3가지 머지 방식을 제공합니다.

 

 

 

1. Create a merge commit (기본)

bash

# 모든 커밋 이력이 보존됨
# 머지 커밋이 생성됨

git merge --no-ff feature/user-authentication

장점:

• 완전한 히스토리 보존
• 브랜치 흐름을 명확히 볼 수 있음

단점:

• 커밋 히스토리가 복잡해질 수 있음

2. Squash and merge (권장)

 

 

bash

# 여러 커밋을 하나로 합침
# 깔끔한 히스토리 유지

git merge --squash feature/user-authentication
git commit -m "feat: 사용자 인증 기능 구현 (#45)"

장점:

• 깔끔한 커밋 히스토리
• 하나의 기능 = 하나의 커밋

단점:

• 세부 커밋 이력이 사라짐

3. Rebase and merge (고급)

 

 

bash

# 커밋들을 base 브랜치 위로 재배치
# 선형 히스토리 유지

git rebase develop
git checkout develop
git merge feature/user-authentication

장점:

• 가장 깔끔한 선형 히스토리
• 머지 커밋이 생성되지 않음

단점:

• 히스토리 변경으로 인한 리스크
• 팀 전체가 이해해야 함

머지 방식 비교표

방식히스토리사용 시점난이도

Merge commit	복잡	브랜치 흐름 유지 필요시	⭐
Squash merge	깔끔	일반적인 경우 (권장)	⭐
Rebase merge	매우 깔끔	선형 히스토리 필요시	⭐⭐⭐

머지 실행

1. PR 페이지 하단의 "Merge pull request" 버튼 클릭
2. 머지 방식 선택 (Squash and merge 권장)
3. 커밋 메시지 확인/수정
4. "Confirm merge" 클릭

머지 후 정리

bash

# 로컬 브랜치로 이동
git checkout develop

# 최신 상태로 업데이트
git pull origin develop

# 작업 브랜치 삭제 (로컬)
git branch -d feature/user-authentication

# 작업 브랜치 삭제 (원격)
git push origin --delete feature/user-authentication

💡 팁: GitHub에서 PR 머지 시 "Delete branch" 옵션을 체크하면 원격 브랜치가 자동 삭제됩니다.

- PR 작성 모범 사례

1. 작은 PR이 좋은 PR

❌ 나쁜 예: 1000줄 변경, 10개 파일 수정
✅ 좋은 예: 200줄 변경, 3-4개 파일 수정

💡 이유:
- 리뷰어가 집중하기 쉬움
- 버그 발견 확률 증가
- 빠른 피드백 가능

2. 명확한 제목과 설명

markdown

❌ 나쁜 예:
제목: 작업 완료
설명: 요청하신 기능 만들었습니다.

✅ 좋은 예:
제목: feat: 사용자 프로필 이미지 업로드 기능 추가
설명:
- S3 버킷 연동
- 이미지 리사이징 (최대 500x500)
- 지원 포맷: JPG, PNG (최대 5MB)

3. 테스트 포함

markdown

## 테스트
- [ ] 단위 테스트 작성 및 통과
- [ ] 통합 테스트 작성 및 통과
- [ ] 수동 테스트 완료
- [ ] 브라우저 호환성 테스트 (Chrome, Safari, Firefox)

4. 스크린샷/GIF 첨부

UI 변경이 있는 경우 시각적 자료를 첨부합니다.

markdown

## Before / After

### Before
![기존 화면](before.png)

### After
![변경 화면](after.png)

## 동작 영상
![기능 시연](demo.gif)

5. 관련 이슈/PR 연결

 

markdown

## 관련 이슈
Closes #123
Fixes #456
Related to #789

## 관련 PR
Depends on #100
Blocks #101

6. 체크리스트 활용

markdown

## PR 체크리스트
- [x] 코드 컨벤션 준수
- [x] 테스트 코드 작성
- [x] 문서 업데이트
- [x] CHANGELOG 업데이트
- [ ] 성능 테스트 완료

- PR 템플릿 설정하기

팀에서 일관된 PR을 작성하도록 템플릿을 설정할 수 있습니다.

GitHub PR 템플릿 생성

프로젝트 루트에 .github 폴더를 만들고 템플릿 파일을 추가합니다.

 

 

bash

# 디렉토리 생성
mkdir -p .github

# PR 템플릿 파일 생성
touch .github/PULL_REQUEST_TEMPLATE.md

템플릿 예시

 

 

markdown

## 작업 내용
<!-- 이 PR에서 무엇을 했는지 간단히 설명해주세요 -->

## 변경 사항
<!-- 구체적인 변경 내용을 나열해주세요 -->
- 
- 

## 테스트 방법
<!-- 리뷰어가 테스트할 수 있는 방법을 설명해주세요 -->
1. 
2. 
3. 

## 스크린샷
<!-- UI 변경이 있다면 Before/After 스크린샷을 첨부해주세요 -->

## 관련 이슈
<!-- 관련된 이슈 번호를 적어주세요 -->
- Closes #
- Related to #

## 체크리스트
- [ ] 코드 리뷰 준비 완료
- [ ] 테스트 완료
- [ ] 문서 업데이트 완료
- [ ] CI/CD 테스트 통과

## 리뷰어에게
<!-- 특별히 확인해주었으면 하는 부분이 있다면 적어주세요 -->

템플릿을 커밋하면 이후 모든 PR 생성 시 자동으로 적용됩니다.

 

 

bash

git add .github/PULL_REQUEST_TEMPLATE.md
git commit -m "docs: PR 템플릿 추가"
git push origin main

- Draft PR 활용하기

Draft PR이란?

작업이 완료되지 않았지만 진행 상황을 공유하고 싶을 때 사용합니다.

 

Draft PR 생성

1. PR 생성 시 "Create pull request" 드롭다운 클릭
2. "Create draft pull request" 선택
3. 작업 완료 후 "Ready for review" 버튼 클릭

Draft PR 활용 시나리오

✅ 이럴 때 사용하세요:
- 작업 방향이 맞는지 미리 확인받고 싶을 때
- CI/CD 테스트를 먼저 돌려보고 싶을 때
- 팀원들에게 진행 상황을 공유하고 싶을 때
- 큰 작업을 진행하며 중간 피드백이 필요할 때

❌ 이럴 때는 피하세요:
- 이미 완성된 코드
- 긴급한 버그 수정

- 실전 예시: PR 전체 플로우

실제 작업 흐름을 처음부터 끝까지 살펴보겠습니다.

시나리오: 회원가입 기능 추가

 

bash

# 1. 최신 develop 브랜치 업데이트
git checkout develop
git pull origin develop

# 2. 기능 브랜치 생성
git checkout -b feature/user-signup

# 3. 작업 진행
# ... 파일 수정 및 코드 작성 ...

# 4. 커밋
git add .
git commit -m "feat: 회원가입 기능 구현

- 회원가입 폼 UI 추가
- 이메일 중복 체크 API 구현
- 비밀번호 유효성 검사 추가
- 회원가입 성공 시 이메일 발송"

# 5. 원격 푸시
git push origin feature/user-signup

# 6. GitHub에서 PR 생성
# - 제목: feat: 회원가입 기능 구현
# - 설명: 템플릿에 따라 작성
# - 리뷰어: 팀 리더, 백엔드 개발자
# - 레이블: feature, needs review

# 7. 리뷰 받기 및 수정
# ... 리뷰 코멘트에 따라 수정 ...

git add .
git commit -m "review: 비밀번호 정규식 수정"
git push origin feature/user-signup

# 8. 승인 받고 머지
# GitHub에서 "Squash and merge" 선택

# 9. 정리
git checkout develop
git pull origin develop
git branch -d feature/user-signup
git push origin --delete feature/user-signup

- 자주 하는 실수와 해결법

1. Base 브랜치를 잘못 선택함

문제:

main으로 PR을 만들어야 하는데 develop으로 만들었다

해결:

PR 페이지에서 "Edit" 버튼 클릭 → base 브랜치 변경

2. 큰 PR 만들기

문제:

1000줄 변경, 20개 파일 수정
리뷰어가 리뷰하기 어려움

해결:

PR을 여러 개로 분할
- PR 1: 데이터베이스 모델 추가
- PR 2: API 엔드포인트 구현
- PR 3: UI 컴포넌트 추가

3. 커밋 메시지가 엉망

문제:

git commit -m "수정"
git commit -m "ㅇㅇ"
git commit -m "aaa"

해결:

 

bash

# 커밋 합치고 메시지 수정
git rebase -i HEAD~3
# 에디터에서 squash 선택 및 메시지 수정
git push origin feature-branch --force

4. 충돌(Conflict) 발생

문제:

base 브랜치가 업데이트되어 충돌 발생

해결:

 

 

bash

# 방법 1: Merge (권장)
git checkout feature/my-feature
git merge develop
# 충돌 해결 후
git add .
git commit -m "merge: resolve conflicts with develop"
git push origin feature/my-feature

# 방법 2: Rebase (고급)
git checkout feature/my-feature
git rebase develop
# 충돌 해결 후
git add .
git rebase --continue
git push origin feature/my-feature --force

5. PR을 잘못 만들어서 닫음

문제:

실수로 PR을 닫았는데 다시 열고 싶다

해결:

PR 페이지 하단의 "Reopen" 버튼 클릭

- PR 리뷰어를 위한 팁

좋은 코드 리뷰 작성법

1. 구체적으로 작성하기

markdown

❌ 나쁜 예:
"이 부분 고쳐주세요"

✅ 좋은 예:
"이 함수는 200줄이 넘어서 가독성이 떨어집니다.
사용자 검증 로직을 별도 함수로 분리하는 것이 어떨까요?
```javascript
function validateUser(user) {
  // 검증 로직
}
```
"

 

2. 긍정적인 피드백도 남기기

markdown

👍 좋은 코드 리뷰:
"에러 핸들링을 꼼꼼하게 처리하셨네요! 👍"
"이 부분 리팩토링 정말 깔끔합니다!"

 

3. 질문으로 시작하기

 

 

markdown

❌ 명령조:
"이 변수명을 바꾸세요"

✅ 질문형:
"`userInfo` 대신 `userData`가 더 명확할 것 같은데 어떻게 생각하시나요?"

리뷰 우선순위

우선순위항목예시

P0 (Critical)	버그, 보안 이슈	SQL 인젝션 취약점
P1 (Important)	성능 문제, 잘못된 로직	N+1 쿼리 문제
P2 (Normal)	코드 품질, 가독성	변수명, 함수 분리
P3 (Nice to have)	스타일, 취향	코드 포맷팅

마무리

이번 시간에는 Pull Request(PR)와 Merge Request(MR) 작성법에 대해 알아봤습니다. PR은 단순히 코드를 병합하는 도구가 아니라, 팀원들과 소통하고 코드 품질을 높이는 협업의 핵심입니다. 좋은 PR 작성 습관을 들이면 팀 전체의 생산성이 향상됩니다.

다음 시간에는 Git Stash - 임시 저장 활용법에 대해 알아보겠습니다.