GitLab 협업 가이드: Issue → 브랜치 → MR → Merge 전체 프로세스
이 문서를 작성한 이유
현재 우리 팀에서는 GitLab의 Issue와 Merge Request를 활용하여 코드 작업을 관리하고 있습니다.
하지만 처음 사용하는 분들이나, 협업 중간에 흐름을 놓친 분들에게는
“어떻게 시작해서 어떤 순서로 작업하고 머지하는지” 헷갈릴 수 있겠다고 느꼈습니다.
그래서 이 문서는:
- 팀 내부에서 Issue를 기반으로 개발을 시작해 MR까지 이어지는 전체 작업 흐름을 기록하고
- 나 자신에게는 작업 플로우를 체계화하고 재사용할 수 있는 기준을 만들며
- 다른 분들에게도 처음 시작할 때 참고가 되는 안내서가 되기를 바라는 마음에서 작성했습니다.
GitLab의 Merge Request(MR)는 왜 중요한가요?
GitLab의 MR은 단순히 "코드를 머지하는 절차"가 아니라,
작업의 목적과 흐름을 문서화하고, 여러 사람과 커뮤니케이션하며, 리뷰를 통해 품질을 높이는 협업 중심 도구입니다.
아래는 GitLab MR의 주요 특징입니다.
🔍 1. 코드의 목적과 내용 파악 용이
요구사항 또는 이슈를 적어서 상세한 작업 내용을 공유합니다.
이것으로 해당 코드가 어떤 기능을 구현했는지, 어떤 문제를 해결했는지 등
코드의 목적과 내용을 비개발자도 충분히 쉽게 이해할 수 있습니다.
💬 2. 댓글을 통한 커뮤니케이션
MR에서는 댓글(Comment) 기능을 통해 서로 피드백을 주고받으며,
"어떤 점이 부족한지", "추가 의견은 무엇인지" 등
생각을 명확하게 공유할 수 있습니다.
✅ 3. 코드리뷰 환경 제공
관련 커밋 목록, 코드 변경점(Code diff), 코멘트 기능 등을 통해
코드 리뷰에 필요한 모든 정보가 하나에 모여 있어
리뷰하기 좋은 구조를 제공합니다.
🛡 4. 관리 기능
코드 승인과 머지 여부를 담당할 **관리자(Approver)**를 지정할 수 있어,
팀 내 품질 보증 및 승인 체계를 구축하는 데에도 유용합니다.
각 담당자별 MR 사용시 장점
https://www.youtube.com/watch?v=Ht8Spfg_4lQ&ab_channel=InfoGrab
Git Issue 등록부터 MR까지의 프로세스
Gitlab에서는 Issue를 등록하고 MR을 하는 다음과 같은 프로세스가 존재합니다.
1. GitLab Issue란?
GitLab Issue는 프로젝트 안에서 아래와 같은 내용을 정리하는 작업 단위(Task 카드)입니다.
- 해야 할 일 (To-Do)
- 버그 리포트
- 기능 개선 요청
- 개발 일정 관리
- 업무 히스토리 공유
📌 예:
“로그인 오류 발생 시 사용자에게 메시지를 보여주자”
→ 이걸 Issue로 만들면, 누가/언제/어떻게 처리할지 기록하고 협업할 수 있어요.
2단계. GitLab에서 Issue는 어디에 있나요?
- GitLab에서 원하는 프로젝트로 들어갑니다.
- 좌측 메뉴에서 Issues > List 클릭
→ 지금까지 생성된 모든 이슈 목록이 보입니다. - 새로운 이슈를 만들고 싶다면 New issue 버튼 클릭
3단계. 새로운 이슈 만들기
| 항목 | 설명 |
| Title (제목) | 한 줄 요약 – 어떤 문제인지 명확히 |
| Description (내용) | 상세 설명, 첨부 이미지, 체크리스트 등 작성 가능 |
| Assignee | 담당자 지정 (누가 이 이슈를 처리할지) |
| Labels | 태그 분류 (bug, feature, urgent, backend 등) |
| Milestone | 특정 릴리즈나 기간 단위 묶음 설정 |
| Due Date | 마감일 설정 가능 |
4단계. 이슈와 Merge Request 연결
- 이슈에서 작업 후 Merge Request(MR)를 만들면 좋습니다.
- MR 설명에 Closes #이슈번호라고 작성하면
- 머지 시 해당 이슈가 자동으로 닫힘 처리됩니다.
📌 예: Closes #12
→ Merge하면 이슈 #12가 자동 종료됩니다.
5단계. 이슈 진행 상황 추적하기
GitLab에서는 이슈들을 보드 형식(Board View)으로도 볼 수 있어요.
예: 칸반보드 구성
| To Do | Doing | Review | Done |
| 새 기능 기획 | 프론트 개발 | QA 요청 | 머지 완료 |
- Issues > Boards에서 칸반보드 사용 가능
- 각 상태는 Label로 자동 분류됨 (doing, review, done 등)
6단계. 실무에서 자주 쓰는 기능
| 기능 | 사용법 |
| 체크리스트 | - [ ] 항목내용 작성 |
| 코드블럭 | ````markdown``코드 작성` |
| @멘션 | @이름 으로 사람 호출 |
| 관련 이슈 링크 | #123 입력하면 자동 링크 |
| 이슈 검색 | Labels, Author, Milestone 기준 필터 가능 |
7단계. 이슈에서 실제 개발 작업 시작하기
이제 이슈를 바탕으로 실제 개발을 시작합니다.
보통 아래처럼 진행됩니다.
💡 예시 이슈
이슈 제목: 로그인 버튼 클릭 시 반응 없음 (#12)
담당자: 김개발
📌 이슈를 기준으로 새로운 브랜치를 만듭니다.
# 1. 로컬에서 새 브랜치 생성 (이슈번호 포함 이름 추천)
git checkout -b fix/login-button-issue-12브랜치 이름 예시: feature/회원가입-구현-#15, bugfix/login-error-#12
8단계. 코드 수정 및 커밋
- 해당 브랜치에서 문제를 해결하거나 기능을 개발합니다.
- 작업 후 커밋:
git add .
git commit -m "Fix: 로그인 버튼 반응 없음 해결 (Closes #12)"
git push origin fix/login-button-issue-12🧠 Closes #12를 커밋 메시지나 MR 설명에 넣으면 이슈 자동 종료 처리가 됩니다.
9단계. GitLab에서 Merge Request 만들기
- 브랜치를 push하면 GitLab에 자동으로 "Merge Request 만들기" 알림이 뜹니다.
또는 좌측 메뉴 Merge Requests > New Merge Request 클릭 - 아래 항목을 채웁니다:
| 항목 | 설명 |
| Source branch | fix/login-button-issue-12 등 새로 만든 브랜치 |
| Target branch | 보통 main 또는 develop |
| Title | 간결하게: Fix: 로그인 오류 해결 |
| Description | 작업 내용 설명 + Closes #12 명시 |
| Assignee | 리뷰 담당자 지정 (선택) |
3. Create merge request 클릭
📌 이때 MR 상태는 Draft 상태로 시작될 수 있습니다.
→ 실제 리뷰를 받기 전에는 "Mark as ready" 버튼을 눌러 검토 가능 상태로 전환해야 합니다.
10단계. 코드 리뷰 및 Merge
- 팀원이 Merge Request를 열어 코드를 리뷰합니다.
- 수정 요청(Comment) → 반영 → 다시 Push 하면 MR에 자동 반영됩니다.
- 리뷰가 완료되면:
- ✅ "Merge" 버튼 클릭
- ✅ MR 설명에 Closes #12가 있으면 → 자동으로 이슈가 종료됨
GitLab에서는 머지 시 Fast-forward, Squash, Rebase 옵션도 선택할 수 있습니다 (팀 규칙에 따라 다름).
11단계. 완료된 작업 확인하기
- Issues > List 에서 #12는 자동으로 Closed 상태가 됩니다.
- Issues > Boards 에서 해당 이슈가 Done 칼럼으로 자동 이동 (Label 설정 시)
💬 실무에서는 머지 완료 후에도 릴리즈 또는 배포 태그 작업까지 연결되기도 합니다.
출처