협업·Pull Request 매뉴얼
이슈로 일을 추적하고, Pull Request로 변경을 제안·리뷰·병합하는 GitHub 협업 워크플로우 | 공식 문서: docs.github.com/pull-requests
gh --version 으로 설치된 GitHub CLI 버전을 확인협업 흐름 한눈에
협업 워크플로우 ├── 이슈(Issue) # 버그·기능·아이디어를 추적 (gh issue create) │ └── 담당자·라벨·마일스톤 지정 # --assignee @me, --label "bug" ├── 브랜치(Branch) # 작업용 브랜치 분기 (git switch -c) ├── Pull Request # 변경을 합치자는 제안 (gh pr create) │ ├── head(compare) → base # 내 변경 → 합쳐 넣을 대상 브랜치 │ └── Draft PR # 작업 중 표시, 병합 불가 (--draft) ├── 리뷰(Review) # gh pr review │ ├── Comment # 피드백만 │ ├── Approve # 승인 │ └── Request changes # 수정 요구 ├── 머지(Merge) # base 브랜치에 병합 │ ├── Merge commit # 커밋 전부 보존 (기본) │ ├── Squash and merge # 단일 커밋으로 합침 │ └── Rebase and merge # 선형 히스토리, 새 SHA └── 이슈 자동 종료 # Fixes #123 (기본 브랜치 대상일 때만)
1. Pull Request 만들기
base / compare(head) — PR의 두 브랜치
Pull Request는 "내 코드 변경을 합치자"는 제안입니다. head 브랜치(compare·소스, 내가 작업한 변경)를 base 브랜치(대상, 합쳐 넣을 기존 브랜치)에 병합하도록 요청합니다. 예를 들어 feature-login 브랜치의 작업을 main 에 합치려면 head는 feature-login, base는 main 입니다.
# feature-login(head) → main(base) 로 합치자는 제안 head: feature-login → base: main
gh pr create — 현재 브랜치로 PR 생성
현재 체크아웃된 브랜치를 head로 삼아 PR을 만들고 생성된 PR의 URL을 출력합니다. --base, --head, --title, --body, --reviewer, --label 로 세부 항목을 지정하고, --fill 을 쓰면 커밋 메시지로 제목·본문을 자동으로 채웁니다.
gh pr create --base main --title "로그인 버그 수정" --body "Fixes #42" --reviewer monalisa gh pr create --fill
gh pr create --web — 브라우저에서 마무리
로컬에서 입력한 제목·본문을 그대로 가지고 브라우저의 PR 생성 화면을 엽니다. 라벨·리뷰어·마일스톤을 웹 UI에서 시각적으로 마저 고르고 싶을 때 유용합니다.
gh pr create --web --base main --title "로그인 버그 수정"
--draft — 작업 중(Draft) PR
아직 리뷰받을 준비가 안 된 작업 중 PR을 만듭니다. Draft 상태에서는 병합이 막히고, CODEOWNERS 기반 자동 리뷰 요청도 발생하지 않습니다. 작업이 끝나면 "Ready for review"로 전환해 정식 리뷰를 받습니다.
gh pr create --draft --title "WIP: 결제 모듈" # 완료 후 웹 PR 화면에서 "Ready for review" 클릭, 또는: gh pr ready
2. 코드 리뷰
gh pr review — 3가지 리뷰 상태
리뷰는 세 상태 중 하나로 제출합니다. Comment는 승인·반려 없이 피드백만, Approve는 변경을 승인, Request changes는 수정을 요구하며 보통 병합을 막습니다. 번호를 생략하면 현재 브랜치의 PR이 대상이 됩니다.
gh pr review --approve gh pr review 123 --request-changes --body "테스트 추가 필요" gh pr review --comment -b "확인 부탁"
--reviewer / CODEOWNERS — 리뷰 요청
저장소 소유자·협업자가 특정 사용자에게 리뷰를 요청할 수 있습니다. PR 생성 시 --reviewer 로 지정하거나, 저장소에 CODEOWNERS 파일을 두면 해당 경로 변경 시 코드 오너에게 리뷰가 자동 요청됩니다.
gh pr create --reviewer monalisa,hubot # .github/CODEOWNERS 예: 경로별 코드 오너 지정 # /src/payments/ @billing-team
라인 코멘트 / Suggestion — 줄 단위 피드백
Files changed 탭에서 변경된 줄 옆의 + 를 눌러 특정 줄에 코멘트를 달거나, 수정 제안(Suggestion)으로 바뀐 코드를 직접 제시할 수 있습니다. 작성자가 제안을 적용하거나 토론이 끝나면 스레드는 "resolved"로 표시됩니다.
# Files changed 탭에서 줄 옆 [+] 클릭 → 코멘트 또는 "Suggestion" 작성 # 제안 적용 / 토론 종료 시 스레드가 "resolved" 처리됨
3. 머지 방식
merge / squash / rebase — 세 가지 병합 전략 비교
GitHub은 세 가지 병합 방식을 제공하며, 각각 base 브랜치에 남는 히스토리 모양이 다릅니다. 한 번 결정되면 되돌리기 어려우므로 팀 정책에 맞춰 고릅니다.
| 방식 | 히스토리에 남는 모양 | 특징·주의 |
|---|---|---|
Merge commit |
모든 커밋 + 머지 커밋 1개(--no-ff) |
개별 커밋 히스토리를 전부 보존. 기본값이지만 그래프가 복잡해질 수 있음 |
Squash and merge |
PR의 모든 커밋을 합친 단일 커밋 | 히스토리가 깔끔. 다만 추적성이 낮고, 장기 브랜치엔 반복 충돌로 비권장 |
Rebase and merge |
머지 커밋 없이 커밋들을 base에 개별로 얹음 | 선형 히스토리. 새 commit SHA가 생성되며, 충돌·unsafe 시 자동 실패 |
💡 핵심 한 줄: 보존이 중요하면 Merge commit, 깔끔함이 중요하면 Squash, 선형 히스토리를 원하면 Rebase 입니다.
머지 후 정리 — 로컬 최신화와 브랜치 삭제
병합이 끝났다고 한 바퀴가 닫히는 것은 아닙니다. 병합은 원격(base)에서 일어났을 뿐, 내 로컬 base 브랜치는 아직 옛날 상태입니다. base로 옮겨 git pull로 병합된 내용을 받아 최신화하고, 역할을 다한 기능 브랜치는 원격·로컬 양쪽에서 지워 저장소를 깔끔하게 유지합니다.
git switch main git pull # 병합된 변경을 로컬 main에 반영 git branch -d feature-x # 다 쓴 로컬 브랜치 삭제(이미 병합된 것만 지움)
git branch -d는 base에 이미 병합된 브랜치만 지웁니다. "병합되지 않았다"며 거부하면 정말 합쳐졌는지 다시 확인하고, 확실히 버려도 될 때만 대문자 -D로 강제 삭제하세요. 원격 브랜치는 PR 병합 화면의 Delete branch 버튼으로 정리합니다.4. 이슈와 자동 연결
gh issue create — 이슈 생성
버그·기능·아이디어를 추적할 이슈를 만듭니다. --title, --body, --label, --assignee(자신은 @me), --milestone, --web 옵션으로 세부 항목을 지정합니다.
gh issue create --title "로그인 시 500 에러" --label "bug,help wanted" gh issue create --title "다크 모드 추가" --label "enhancement" --assignee "@me"
Fixes #123 — closing keywords로 자동 종료
PR 본문이나 커밋 메시지에 closing keyword + 이슈 번호를 적으면, 그 PR이 병합될 때 연결된 이슈가 자동으로 닫힙니다. 사용 가능한 키워드는 close / closes / closed / fix / fixes / fixed / resolve / resolves / resolved 입니다.
Fixes #123 # 같은 저장소의 이슈 Fixes OWNER/REPO#100 # 다른 저장소의 이슈
이슈-PR 연결 — 추적의 기본 단위
이슈는 "할 일", PR은 "그 일을 끝낸 변경"입니다. closing keyword로 둘을 연결하면 이슈 화면에서 진행 중인 PR을 추적할 수 있고, 병합 시 이슈가 자동으로 종료되어 추적 누락을 막습니다.
gh pr create --base main --body "Closes #12" --reviewer teammate
5. 포크 기여
gh repo fork — 저장소 포크
쓰기 권한이 없는 오픈소스 저장소에 기여할 때, 저장소를 내 계정으로 복제(fork)합니다. --clone 을 주면 로컬에 클론까지 하며, 원본은 upstream, 내 포크는 origin 으로 리모트가 설정됩니다.
gh repo fork octocat/Spoon-Knife --clone gh repo fork owner/project --clone # origin=내 포크, upstream=원본
upstream — 원본과 동기화
포크 후에는 원본(upstream)의 최신 변경을 받아 그 위에서 작업해야 충돌을 줄일 수 있습니다. git fetch upstream 으로 원본을 가져온 뒤 그 기본 브랜치에서 새 작업 브랜치를 분기합니다.
git fetch upstream git switch -c add-feature upstream/main
리모트 구성 — origin과 upstream
포크 기여의 리모트 구성을 정리하면 다음과 같습니다. 내 변경은 origin(내 포크)에 푸시하고, 원본을 향한 PR은 그 base로 원본 저장소의 기본 브랜치를 사용합니다.
| 리모트 | 가리키는 곳 | 용도 |
|---|---|---|
origin |
내 계정의 포크 | git push -u origin <branch> 로 내 변경을 올림 |
upstream |
원본 저장소 | git fetch upstream 으로 최신 변경을 동기화 |
Fixes #123)는 PR이 저장소의 기본 브랜치를 대상으로 할 때만 작동합니다. 다른 브랜치를 base로 한 PR에서는 이슈가 닫히지 않으니, 자동 종료를 의도했다면 base가 기본 브랜치인지 먼저 확인하세요.참고 링크
- 📖 GitHub Docs — Pull requests
- 🐞 GitHub Docs — Issues
- ⚙️ gh pr create — GitHub CLI manual
- ⚙️ gh pr review — GitHub CLI manual
- ⚙️ gh issue create — GitHub CLI manual
- ⚙️ gh repo fork — GitHub CLI manual
GitHub 웹/CLI 2026-06 기준 | 2026년 6월