git

🤝 GitHub 협업 워크플로우 완전 정복 — PR, Issue, Review의 모든 것

mirabo01 2025. 11. 4. 22:09

Git을 혼자 쓸 땐 단순하지만,
팀으로 협업하기 시작하면 GitHub의 진짜 힘이 드러난다.

오늘은 실무에서 꼭 알아야 할 3가지 협업 핵심 도구 —
✅ Pull Request (PR)
✅ Issue
✅ Code Review
를 중심으로, 효율적인 협업 흐름을 단계별로 정리해본다.

💡 1. 협업의 기본: “main을 건드리지 않는다”

“팀 프로젝트의 첫 번째 규칙: main 브랜치는 절대 직접 수정하지 않는다.”

main은 서비스가 실제로 배포되는 가장 안정적인 버전이다.
따라서 모든 변경은 별도의 브랜치에서 작업 → PR로 병합 요청
이라는 과정을 반드시 거쳐야 한다.

💬 쉽게 말하면,

“main은 교본이고, 나머지 브랜치는 실험실이다.”

🌱 2. 작업 전 기본 플로우

협업은 아래 순서를 습관처럼 반복한다 👇

git clone → git branch → git commit → git push → Pull Request

실무에서는 이걸 ‘PR 기반 워크플로우’ 라고 부른다.

💬 “PR 없이는 main에 합쳐지지 않는다”는 원칙이 팀을 지켜준다.

⚙️ 3. Issue — 작업 시작의 출발점

“Issue는 프로젝트의 모든 할 일, 버그, 개선 요청의 공식 기록지다.”

GitHub 저장소의 Issues 탭을 열면,
작업할 항목을 “이슈 티켓” 형태로 관리할 수 있다.

✅ 예시

제목 내용 담당자 라벨

[Feature] 로그인 API 연동 로그인 폼과 API 연결 구현 Jo Kibeom feature
[Bug] 모바일 화면 깨짐 375px 이하에서 깨짐 현상 Park Dev bug

💡 Issue의 장점

  • 할 일 명확화 (To-Do 관리)
  • 팀원 간 역할 분담
  • 커밋과 PR에 연결 가능

🧩 4. Branch 생성 — Issue 기반으로 브랜치명 짓기

이슈를 만들었다면,
그 번호를 기반으로 브랜치를 생성하는 게 일반적이다 👇

git switch -c feature/#45-login-api

✅ 예시:
Issue #45 → 로그인 API 작업
→ 브랜치 이름: feature/#45-login-api

💬 “Issue 번호가 곧 커밋 이력의 맥락이 된다.”

🚀 5. Pull Request (PR) — 협업의 핵심

“내 코드가 main에 합쳐지기 전, 팀원에게 검토를 요청하는 절차”

작업이 끝났다면 push 한 뒤,
GitHub 저장소에서 Pull Request 생성을 클릭한다.

PR 작성 예시

항목 내용

제목 [Feature] 로그인 API 연동
설명 - 로그인 폼과 백엔드 API 연결 완료- 에러 처리 로직 추가
연결된 이슈 Closes #45
리뷰어 지정 @teamleader
라벨 feature

💡 “Closes #45”를 적으면,
PR이 머지되면서 Issue #45가 자동으로 닫힌다.

🔍 6. 코드 리뷰 (Code Review)

팀장은 PR을 보고 코드 품질을 확인한다.
GitHub은 PR 화면에서 아래처럼 리뷰를 남길 수 있다 👇

  • 💬 Comment: 단순 의견
  • ✅ Approve: 병합 승인
  • ❌ Request changes: 수정 요청

리뷰 완료 후에는 팀 규칙에 따라 다음 중 하나를 선택한다:

  • 승인 1회 이상 시 자동 병합
  • 모든 리뷰 통과 후 수동 병합

💬 리뷰는 단순히 오류 찾기가 아니라, 팀의 코드 품질 문화다.

🧠 7. 병합(Merge) 방식 3가지

PR을 승인받으면 병합(Merge)을 선택할 수 있다 👇

방식 설명 장점

Merge commit 새 병합 커밋 생성 기록 보존
Squash and merge 모든 커밋을 1개로 압축 깔끔한 히스토리
Rebase and merge 직선형 히스토리 유지 병합 이력 단순화

💡 스타트업/소규모 팀이라면
→ “Squash and merge” 추천 (커밋 히스토리 간결)

🧩 8. PR 병합 후 정리 루틴

  1. main 브랜치로 이동
  2. git switch main git pull origin main
  3. 작업 브랜치 삭제
  4. git branch -d feature/#45-login-api
  5. GitHub 원격 브랜치 삭제 (선택)
  6. git push origin --delete feature/#45-login-api

✅ 이렇게 하면 저장소가 깔끔하게 유지된다.

⚡ 9. 협업 품질을 높이는 GitHub 기능 3가지

기능 설명

Projects 칸반보드 형식의 일정 관리
Milestones 릴리즈별 이슈 묶기
Labels 작업 성격별 색상 태그 (bug, feature, refactor 등)

💬 GitHub은 단순 저장소가 아니라, 팀 협업 플랫폼이다.
이 기능들을 쓰면 Jira나 Notion 없이도 프로젝트를 완전히 관리할 수 있다.

🧭 10. 실무 협업 플로우 요약

1️⃣ Issue 생성 → 작업 내용 정의 
2️⃣ 브랜치 생성 (feature/#이슈번호) 
3️⃣ 코드 작성 & 커밋 
4️⃣ push 후 Pull Request 생성 
5️⃣ 리뷰 → 수정 반영 
6️⃣ Merge 후 브랜치 삭제

💡 이 구조가 바로 모든 스타트업, 오픈소스, 실무 팀의 기본 협업 루틴이다.

🧩 11. 실전 팁 — 협업 메시지 템플릿

✅ 커밋 메시지

feat: 로그인 API 연동 (#45)

✅ PR 제목

[Feature] 로그인 API 연동 (#45)

✅ PR 본문

### 작업 내용 
- 로그인 폼에서 API 호출 구현 
- 오류 메시지 UI 추가 
 
### 테스트 방법 
1. 로그인 화면 접속 
2. 유효하지 않은 입력 시 에러 표시 확인 
 
Closes #45

💬 팀 내에서 템플릿을 정해두면, PR 품질이 급상승한다.

🏁 마무리 — “Pull Request는 코드 품질의 필터다”

GitHub 협업은 결국 PR 문화가 얼마나 잘 정착되었는가로 결정된다.
코드를 합치는 행위보다, 리뷰와 소통의 과정이 중요하다.

💬 “좋은 팀은 코드를 병합하는 게 아니라,
서로의 생각을 병합한다.”

다음 편에서는
✅ Git Hooks와 GitHub Actions를 활용해
PR 이후의 자동화된 배포 파이프라인 (CI/CD) 를 구성해보자.