[Error] GitHub Only one pull request 오류 원인과 해결 방법

GitHub Only one pull request 오류 원인과 해결 방법

GitHub에서 Pull Request를 생성하려고 할 때 "Only one pull request may be open for a given source and target branch"라는 오류 메시지를 만나면 당황스러울 수 있습니다. 이 오류는 동일한 소스 브랜치와 대상 브랜치 조합으로 이미 열려 있는 Pull Request가 존재할 때 발생합니다. 이 글에서는 오류의 정확한 원인부터 상황별 해결 방법까지 자세히 알아보겠습니다.

목차

1. Only one pull request 오류란

2. 오류가 발생하는 원인

3. 오류 해결 방법

4. 오류 예방 전략

5. 자주 묻는 질문

---

#1. Only one pull request 오류란

1) 오류 메시지의 의미

"Only one pull request may be open for a given source and target branch"는 GitHub의 Pull Request 정책에 따라 동일한 브랜치 조합에 대해 하나의 PR만 허용된다는 것을 의미합니다.

예를 들어, feature/login 브랜치에서 main 브랜치로의 Pull Request가 이미 열려 있다면, 동일한 조합으로 새로운 Pull Request를 만들 수 없습니다.

.....

2) GitHub Pull Request의 동작 원리

(1) Pull Request의 구성 요소

Pull Request는 다음 세 가지 핵심 요소로 구성됩니다:

① 소스 브랜치(Source Branch): 변경 사항이 있는 브랜치

② 대상 브랜치(Target Branch): 변경 사항을 병합할 브랜치

③ 커밋 내역: 소스 브랜치에 추가된 변경 사항들

(2) 중복 방지 정책

GitHub는 동일한 소스-대상 브랜치 조합에 대해 하나의 활성 PR만 유지하도록 설계되었습니다. 이는 코드 리뷰의 혼란을 방지하고 병합 프로세스를 명확하게 유지하기 위한 조치입니다.

.....

3) 오류 발생 시나리오

이 오류는 주로 다음과 같은 상황에서 발생합니다:

상황	설명
이전 PR 미처리	같은 브랜치로 생성한 이전 PR이 아직 열려 있는 경우
실수로 중복 생성	이미 PR을 만들었는데 다시 생성 버튼을 클릭한 경우
브랜치 재사용	이전에 사용한 브랜치를 다시 사용하여 PR 생성 시도
Draft PR 존재	Draft 상태의 PR이 있는데 새로운 PR을 만들려는 경우

---

#2. 오류가 발생하는 원인

1) 기존 Pull Request 존재

가장 흔한 원인은 동일한 브랜치 조합으로 이미 생성된 Pull Request가 존재하는 경우입니다. 이 PR이 Open 상태이거나 Draft 상태라면 새로운 PR을 만들 수 없습니다.

GitHub 저장소의 Pull Requests 탭에서 현재 열려 있는 모든 PR을 확인할 수 있습니다. 때로는 자신이 만든 PR을 잊어버리거나, 팀원이 동일한 브랜치로 이미 PR을 생성한 경우가 있습니다.

.....

2) 브랜치 이름 혼동

비슷한 이름의 브랜치들을 사용하다 보면 이전에 사용했던 브랜치를 다시 사용하는 경우가 발생합니다. 예를 들어:

① feature/user-auth로 PR을 만들었는데

② 로컬에서 같은 브랜치에 추가 작업을 하고

③ 다시 PR을 만들려고 시도하는 경우

.....

3) Draft Pull Request의 존재

Draft(초안) 상태의 Pull Request도 활성 PR로 간주됩니다. Draft PR을 만들어두고 잊어버린 상태에서 새로운 PR을 생성하려 하면 이 오류가 발생합니다.

# Draft PR도 활성 PR로 카운트됩니다
feature/login → main (Draft PR 상태)
feature/login → main (새 PR 생성 시도) ❌ 오류 발생

.....

4) UI 지연 및 캐싱 문제

GitHub 웹 인터페이스의 일시적인 지연이나 브라우저 캐싱 문제로 인해 이미 PR이 생성되었는데도 생성 버튼이 계속 활성화되어 있는 경우가 있습니다. 이때 버튼을 다시 클릭하면 오류가 발생할 수 있습니다.

---

#3. 오류 해결 방법

1) 기존 Pull Request 확인하기

먼저 GitHub 저장소에서 현재 열려 있는 Pull Request를 확인해야 합니다:

(1) Pull Requests 탭 확인

① GitHub 저장소 페이지로 이동

② 상단의 "Pull requests" 탭 클릭

③ 필터를 "is:open"으로 설정하여 열린 PR 확인

④ 자신의 브랜치로 만든 PR이 있는지 검색

(2) 명령줄로 확인

GitHub CLI를 사용하면 더 빠르게 확인할 수 있습니다:

# GitHub CLI로 열린 PR 목록 확인
gh pr list

# 특정 브랜치의 PR 확인
gh pr list --head feature/login

.....

2) 기존 Pull Request 업데이트하기

새로운 PR을 만들 필요 없이 기존 PR에 변경 사항을 추가할 수 있습니다. 같은 브랜치에 새로운 커밋을 푸시하면 자동으로 기존 PR에 반영됩니다.

# 기존 브랜치에서 추가 작업
git add .
git commit -m "Add additional changes"

# 같은 브랜치로 푸시하면 기존 PR에 자동 반영
git push origin feature/login

이 방법은 코드 리뷰가 진행 중이거나 피드백을 받은 경우 가장 적절합니다. 리뷰어들이 변경 사항을 연속적으로 추적할 수 있습니다.

.....

3) 기존 Pull Request 닫기

(1) 웹에서 닫기

기존 PR이 더 이상 필요하지 않다면 닫을 수 있습니다:

① 해당 Pull Request 페이지로 이동

② 하단의 "Close pull request" 버튼 클릭

③ 새로운 Pull Request 생성

출처 : StackOverflow

(2) CLI로 닫기

# Pull Request 번호를 알고 있는 경우
gh pr close 123

# 특정 브랜치의 PR 닫기
gh pr close --delete-branch feature/old-login

주의: PR을 닫으면 관련된 모든 리뷰와 댓글이 보존되지만 병합은 되지 않습니다.

.....

4) 새로운 브랜치로 Pull Request 만들기

기존 PR을 유지하면서 새로운 작업을 하고 싶다면 새로운 브랜치를 생성하는 것이 좋습니다:

# 현재 브랜치에서 새 브랜치 생성
git checkout -b feature/login-v2

# 또는 최신 main에서 새 브랜치 생성
git checkout main
git pull origin main
git checkout -b feature/login-refactor

# 변경 사항 작업 후 푸시
git push origin feature/login-refactor

이제 새로운 브랜치로 Pull Request를 만들 수 있습니다. 이 방법은 기존 작업과 완전히 분리된 새로운 접근 방식을 시도할 때 유용합니다.

.....

5) Draft Pull Request를 Ready로 전환

Draft 상태의 PR이 있다면, 새 PR을 만들기보다 Draft를 Ready 상태로 전환하는 것이 좋습니다:

① Draft Pull Request 페이지로 이동

② 하단의 "Ready for review" 버튼 클릭

③ PR이 정식으로 리뷰 가능한 상태로 전환됨

# GitHub CLI로 Draft를 Ready로 전환
gh pr ready 123

---

#4. 오류 예방 전략

1) 브랜치 명명 규칙 수립

명확하고 체계적인 브랜치 이름 규칙을 사용하면 혼란을 줄일 수 있습니다:

브랜치 타입	명명 패턴	예시
기능 개발	feature/[이슈번호]-[간단한설명]	feature/123-user-authentication
버그 수정	bugfix/[이슈번호]-[버그설명]	bugfix/456-login-error
핫픽스	hotfix/[심각도]-[문제]	hotfix/critical-security-patch
리팩토링	refactor/[대상]-[목적]	refactor/auth-service-optimization

.....

2) Pull Request 생성 전 체크리스트

PR을 만들기 전에 다음 사항들을 확인하세요:

① 열려 있는 PR 목록 확인: gh pr list 또는 웹에서 확인

② 현재 브랜치 확인: git branch --show-current

③ 대상 브랜치 확인: PR을 어느 브랜치로 병합할지 명확히 파악

④ 최신 커밋 확인: git log --oneline -5로 의도한 변경사항만 포함되었는지 확인

.....

3) 브랜치 정리 자동화

병합 완료된 브랜치를 자동으로 삭제하도록 설정하면 재사용으로 인한 문제를 예방할 수 있습니다:

(1) GitHub 설정에서 자동 삭제 활성화

① 저장소 Settings로 이동

② "Automatically delete head branches" 옵션 활성화

③ PR 병합 시 자동으로 소스 브랜치가 삭제됨

출처 : Github

(2) 로컬 브랜치 정리

# 원격에서 삭제된 브랜치 로컬에서도 제거
git fetch --prune

# 병합 완료된 로컬 브랜치 삭제
git branch --merged main | grep -v "main" | xargs git branch -d

.....

4) Pull Request 템플릿 활용

저장소에 PR 템플릿을 만들어두면 PR 생성 시 필요한 정보를 체계적으로 작성할 수 있고, 중복 생성을 방지할 수 있습니다:

# .github/pull_request_template.md 파일 생성
## 변경 사항
- [ ] 기능 추가
- [ ] 버그 수정
- [ ] 리팩토링

## 관련 이슈
Closes #

## 체크리스트
- [ ] 기존 PR 확인 완료
- [ ] 테스트 통과
- [ ] 문서 업데이트

---

#5. 자주 묻는 질문

1) PR을 닫았다가 다시 열 수 있나요?

네, 가능합니다. 닫힌 Pull Request는 언제든지 다시 열 수 있습니다. PR 페이지 하단의 "Reopen pull request" 버튼을 클릭하면 됩니다. 모든 리뷰와 댓글은 그대로 보존됩니다.

# GitHub CLI로 PR 다시 열기
gh pr reopen 123

.....

2) 같은 커밋을 다른 브랜치로 PR 만들 수 있나요?

네, 소스 브랜치만 다르다면 같은 대상 브랜치로 여러 PR을 만들 수 있습니다. 예를 들어:

① feature/login → main (PR #1) ✅

② feature/signup → main (PR #2) ✅

③ feature/login → main (PR #3) ❌ 중복 오류

.....

3) Force Push하면 기존 PR은 어떻게 되나요?

Force push를 해도 기존 PR은 유지되며 새로운 커밋 내역으로 업데이트됩니다. 다만 리뷰어들에게 히스토리 변경이 통보되므로 신중하게 사용해야 합니다.

# 주의: Force push는 협업 시 신중히 사용
git push --force-with-lease origin feature/login

--force-with-lease 옵션을 사용하면 원격의 변경사항이 있을 때 push를 거부하므로 더 안전합니다.

.....

4) 여러 개의 관련 기능을 개발 중인데 어떻게 PR을 관리하나요?

관련된 기능들을 개발할 때는 다음과 같은 전략을 사용할 수 있습니다:

(1) 스택형 PR (Stacked PRs)

각 기능을 별도 브랜치로 만들고 순차적으로 병합합니다:

main → feature/base → feature/extended → feature/final

# PR 순서
PR #1: feature/base → main
PR #2: feature/extended → feature/base
PR #3: feature/final → feature/extended

(2) 기능별 독립 브랜치

서로 독립적인 기능이라면 각각 별도의 브랜치와 PR로 관리하는 것이 좋습니다. 이렇게 하면 한 기능의 리뷰가 지연되어도 다른 기능은 먼저 병합할 수 있습니다.

.....

5) Draft PR과 일반 PR의 차이는 무엇인가요?

구분	Draft PR	일반 PR
리뷰 요청	리뷰 요청 불가	리뷰 요청 가능
병합 가능 여부	병합 불가	승인 후 병합 가능
알림	제한적 알림	모든 알림 활성화
사용 시기	작업 진행 중, 초기 피드백 필요	리뷰 및 병합 준비 완료
중복 방지	활성 PR로 카운트됨	활성 PR로 카운트됨

두 가지 모두 "활성 PR"로 간주되므로 동일한 브랜치 조합에 대한 중복 생성은 불가능합니다.

---

마무리

"Only one pull request may be open for a given source and target branch" 오류는 GitHub의 Pull Request 정책에 따라 발생하는 자연스러운 제약입니다. 이 오류를 만났을 때는 먼저 기존에 열려 있는 PR이 있는지 확인하고, 상황에 따라 기존 PR을 업데이트하거나 새로운 브랜치를 만들어 해결할 수 있습니다.

가장 중요한 것은 예방입니다. 명확한 브랜치 명명 규칙을 수립하고, PR 생성 전 체크리스트를 활용하며, 병합 완료된 브랜치는 즉시 삭제하는 습관을 들이면 이런 오류를 크게 줄일 수 있습니다. GitHub CLI를 활용하면 명령줄에서 빠르게 PR 상태를 확인하고 관리할 수 있어 효율적입니다.

협업 프로젝트에서는 팀원들과 브랜치 전략을 공유하고, PR 템플릿을 활용하여 일관성 있는 워크플로우를 유지하는 것이 좋습니다. Draft PR 기능도 적극 활용하여 작업 진행 상황을 투명하게 공유하되, 최종적으로는 Ready 상태로 전환하여 정식 리뷰를 받는 프로세스를 확립하시기 바랍니다.

긴 글 읽어주셔서 감사합니다.

끝.