협업·Pull Request 실습 예시

이슈·PR·리뷰·머지를 난이도별 시나리오로 따라 하며 익히는 가이드 | ← 레퍼런스 문서로 돌아가기

대상 버전/범위GitHub 웹 / GitHub CLI(gh) 2026-06 기준

이 파일의 목적매뉴얼의 명령을 실제 협업 흐름에 맞춰 단계별로 보여 줍니다

레퍼런스 문서Collab_Manual.html — 각 시나리오에서 링크로 연결됩니다

작성일2026년 6월 16일

● 초급 Getting Started 내 저장소에서 변경을 브랜치로 분리해 첫 PR을 올려 봅니다

G-1 초급 AI가 고친 버그를 내 저장소 PR로 올리기

내 저장소에 "로그인 시 null 참조 오류"가 이슈 #5로 이미 등록돼 있습니다. AI 도구가 해당 버그를 고쳐 줘서 코드가 로컬에 반영된 상태입니다. 이 변경을 main에 바로 밀어 넣지 않고, 브랜치로 분리해 PR로 올린 뒤 변경 내용을 확인하고 병합하려 합니다.

사용 요소

gh pr create Fixes #5 Files changed

단계별 실행

작업용 브랜치 만들기
고친 코드를 main에서 떼어 내 별도 브랜치에서 다루기 위해 새 브랜치를 만들고 그 브랜치로 전환합니다.
```
git switch -c fix-login-bug
```
변경 커밋하기
AI가 고친 내용을 스테이징하고 무엇을 바꿨는지 알아볼 수 있는 메시지로 커밋합니다.
```
git add .
git commit -m "로그인 null 체크 추가"
```
브랜치 푸시하기
-u로 원격 추적 브랜치를 설정하며 처음 푸시합니다. 이후에는 git push만으로 올릴 수 있습니다.
```
git push -u origin fix-login-bug
```
PR 생성하고 이슈 연결하기
현재 브랜치(fix-login-bug)를 head로 삼아 main에 PR을 만듭니다. 본문에 Fixes #5를 넣어 병합 시 이슈가 자동으로 닫히게 합니다.
```
gh pr create --base main --title "로그인 버그 수정" --body "Fixes #5"
```
Files changed 탭에서 검토 후 병합
출력된 PR URL을 열어 Files changed 탭에서 실제로 무엇이 바뀌었는지 직접 확인합니다. 의도한 변경만 들어 있으면 병합합니다.
```
# PR URL을 열어 "Files changed" 탭 검토
gh pr merge --merge
```

main에 직접 커밋하지 않고 브랜치 → PR을 거치면, 변경이 합쳐지기 전에 한 화면(Files changed)에서 전체 diff를 검토할 수 있습니다. 병합 시 본문의 Fixes #5 키워드가 이슈 #5를 자동으로 닫습니다(기본 브랜치 main 대상이므로 동작).

AI가 고친 코드는 그대로 믿지 말고 Files changed 탭에서 한 줄씩 확인하세요. 의도하지 않은 파일이 함께 바뀌어 있지 않은지 보는 것이 첫 PR의 핵심 습관입니다.

● 중급 Daily Workflow 이슈로 일을 추적하고, 리뷰를 거쳐 Squash로 깔끔하게 병합합니다

D-1 중급 이슈로 추적 + 리뷰 요청 + Squash 머지

팀 저장소에 "다크 모드 추가"라는 기능 요청이 들어왔습니다. 작업을 이슈로 먼저 등록해 추적 가능하게 만들고, 구현 후 동료(teammate)에게 리뷰를 요청해 승인을 받은 뒤, 여러 작업 커밋을 하나로 합쳐 깔끔하게 병합하려 합니다. 저장소에 협업자 teammate가 있고 GitHub CLI에 로그인돼 있다고 전제합니다.

사용 요소

gh issue create gh pr review Squash and merge

단계별 실행

이슈 생성하기
작업을 이슈로 등록해 추적 단위를 만듭니다. 자신을 담당자로 지정하면 진행 주체가 분명해집니다. 생성된 이슈가 #12라고 가정합니다.
```
gh issue create --title "다크 모드 추가" --label "enhancement" --assignee "@me"
```
브랜치 작업 후 PR 생성 + 리뷰 요청
구현·푸시를 마친 뒤, 본문에 Closes #12를 넣고 --reviewer로 동료에게 리뷰를 요청하며 PR을 만듭니다.
```
git switch -c feature-dark-mode
# ... 구현 후 ...
git push -u origin feature-dark-mode
gh pr create --base main --body "Closes #12" --reviewer teammate
```
리뷰어가 수정 요구 → 반영 후 승인
이 PR이 #13으로 생성됐다고 가정합니다(이슈와 PR은 같은 번호 흐름을 공유하므로 이슈 #12 다음 번호가 PR에 붙습니다). 동료가 PR #13에 수정을 요구(Request changes)합니다. 작성자가 피드백을 반영해 추가 커밋을 올리면, 동료가 다시 승인(Approve)합니다.
```
# 동료(리뷰어)
gh pr review 13 --request-changes --body "테스트 추가 필요"
# 작성자가 수정·푸시 후, 동료가 다시:
gh pr review 13 --approve
```
Squash and merge로 병합
승인된 PR을 Squash 방식으로 병합해 작업 커밋들을 단일 커밋으로 합칩니다. 병합되면 Closes #12에 따라 이슈 #12가 자동으로 닫힙니다.
```
gh pr merge 13 --squash
```

이슈(추적) → PR(Closes #12) → 리뷰(Request changes → Approve) → Squash 병합으로 이어지는 흐름입니다. Squash는 PR의 여러 커밋을 하나로 합쳐 main 히스토리를 깔끔하게 유지하고, 병합 시점에 closing keyword가 이슈를 닫아 추적 누락을 막습니다.

Squash는 개별 커밋 히스토리가 단일 커밋으로 합쳐져 추적성이 낮아지고, 오래 유지되는 장기 브랜치에서는 반복 충돌을 일으킬 수 있습니다. 짧게 살다 합쳐지는 기능 브랜치에 쓰고, 머지 방식은 팀에서 미리 합의하세요.

● 고급 Power User 오픈소스를 포크해 upstream과 동기화하고 Draft PR로 기여합니다

P-1 고급 오픈소스 포크 기여 (fork → upstream → Draft PR)

쓰기 권한이 없는 오픈소스 저장소 owner/project에 새 기능을 기여하려 합니다. 저장소를 내 계정으로 포크해 작업하고, 원본의 최신 상태와 동기화한 위에서 구현한 뒤, 아직 작업 중임을 알리는 Draft PR로 먼저 올려 메인테이너의 조기 피드백을 받으려 합니다. GitHub CLI에 로그인돼 있다고 전제합니다.

사용 요소

gh repo fork upstream --draft

단계별 실행

저장소 포크 + 클론
원본을 내 계정으로 포크하고 로컬에 클론합니다. 이때 내 포크가 origin, 원본이 upstream 리모트로 설정됩니다.
```
gh repo fork owner/project --clone
```
upstream 동기화 후 작업 브랜치 분기
원본(upstream)의 최신 변경을 가져와, 그 기본 브랜치 위에서 새 작업 브랜치를 만듭니다. 최신 위에서 시작해야 충돌을 줄일 수 있습니다.
```
git fetch upstream
git switch -c add-feature upstream/main
```
구현 후 내 포크에 푸시
기능을 구현·커밋하고 내 포크(origin)로 브랜치를 푸시합니다.
```
# ... 구현 후 ...
git push -u origin add-feature
```
Draft PR로 올려 조기 피드백
아직 작업 중임을 알리는 Draft PR로 원본의 기본 브랜치를 향해 제안합니다. Draft 상태에서는 병합이 막히고 CODEOWNERS 자동 리뷰 요청도 발생하지 않습니다.
```
gh pr create --base main --draft --title "WIP: 신규 기능"
```
완료 후 Ready for review 전환
작업이 끝나면 Draft를 해제해 정식 리뷰를 받습니다. 메인테이너가 리뷰·체크를 거쳐 병합합니다.
```
gh pr ready
# 또는 웹 PR 화면에서 "Ready for review" 클릭
```

포크 기여는 origin(내 포크)과 upstream(원본) 두 리모트로 움직입니다. upstream/main에서 분기해 충돌을 줄이고, 변경은 origin에 푸시한 뒤 원본 기본 브랜치를 base로 PR을 엽니다. Draft → Ready for review 순서로 진행하면 메인테이너가 미완성 단계부터 방향을 잡아 줄 수 있습니다.

원본 저장소는 브랜치 보호 규칙으로 승인 리뷰·상태 체크를 강제할 수 있습니다. PR을 올리기 전에 upstream을 다시 동기화해 최신 위에서 충돌을 미리 해소하면, 리뷰·체크 통과가 한결 수월합니다.

GitHub 웹/CLI 2026-06 기준 | 2026년 6월 16일 작성
← 협업·Pull Request 매뉴얼