Developer

협업의 꽃인 Pull Request(PR). 하지만 가끔은 갑작스러운 오류로 멘탈이 흔들릴 때가 있습니다.
push가 안 되거나, 버튼이 안 보이거나, 충돌이 날 때마다 검색에 시간을 쓰지 않도록, PR 과정에서 가장 흔한 5가지 문제와 해결법을 한 페이지에 모았습니다.

1) fatal: refusing to merge unrelated histories

로컬과 원격의 커밋 히스토리가 서로 완전히 다를 때 발생합니다.
처음 pull 시도에서나, 로컬에 이미 커밋이 있는 상태에서 원격을 연결하고 pull할 때 자주 보입니다.

해결

서로 관련 없는 히스토리라도 강제로 병합합니다. 이후 충돌이 나면 수정 후 커밋하세요.

# [브랜치_이름]에 main, master, develop 등을 넣으세요.
git pull origin [브랜치_이름] --allow-unrelated-histories

충돌이 발생할 가능성이 높습니다. 에디터에서 표시되는 충돌 마커를 제거하고 정상 코드만 남긴 뒤 커밋하세요.

2) error: failed to push some refs to … (동기화 문제)

다른 팀원이 먼저 원격에 푸시해서, 내 로컬이 최신이 아닐 때 발생합니다.
내가 푸시하면 상대의 커밋을 덮을 수 있어 Git이 차단합니다.

해결

먼저 원격을 받아 병합하고, 그 다음 푸시합니다. 충돌 시 해결 후 커밋하세요.

# 1) 최신 내용 반영
git pull origin [현재_브랜치_이름]

# (충돌 해결 후 커밋)

# 2) 다시 푸시
git push origin [현재_브랜치_이름]

3) Permission denied (publickey) (SSH 권한 문제)

SSH 방식으로 연결했지만, 현재 PC의 공개 키가 GitHub에 등록되지 않았거나, 에이전트가 키를 못 찾을 때 발생합니다.

해결

1) 로컬에 SSH 키가 있는지 확인하고, 없다면 생성합니다.
2) ssh-agent가 실행 중인지 확인하고 키를 추가합니다.
3) GitHub 계정 설정 › SSH and GPG keys에 공개 키를 등록합니다.

# 일반적인 개인키 경로 예시
ssh-add ~/.ssh/id_rsa

공개 키(*.pub) 내용을 복사해 GitHub에 새 키로 등록하세요.

4) PR 생성 버튼이 보이지 않거나 비활성화될 때

GitHub에서 “Compare & pull request” 버튼이 안 보이거나 비활성화되어 있을 수 있습니다.
대부분 아래 셋 중 하나가 원인입니다.

원인과 해결

  • 원인 1: 브랜치를 원격으로 푸시하지 않음
    해결: 작업 브랜치를 푸시합니다. 
    git push origin [내가_작업한_브랜치_이름]

  • 원인 2: 동일 브랜치로 이미 PR이 열려 있음
    해결: 새 PR을 만들지 말고 기존 PR에 커밋을 푸시하면 자동으로 반영됩니다.

  • 원인 3: Base 브랜치와 변경 사항이 없음
    해결: 실제 변경 커밋이 필요합니다. 브랜치 전략을 점검하거나 새로운 변경을 추가하세요.

5) “This branch has conflicts that must be resolved” (병합 충돌)

Base 브랜치(예: main)와 내 브랜치가 같은 파일의 같은 부분을 다르게 수정했을 때 발생합니다.
Git이 어느 쪽을 남길지 결정하지 못해 수동 해결을 요구합니다.

해결 (로컬 권장)

1) Base 브랜치의 최신 내용을 내 브랜치로 가져옵니다.
2) 충돌 파일을 열어 마커(<<<<<<<, =======, >>>>>>>)를 기준으로 남길 코드를 선택합니다.
3) 마커를 모두 삭제하고 저장한 뒤, 커밋합니다.
4) 다시 푸시하면 PR의 충돌 경고가 사라집니다.

# 1) 최신 Base 브랜치 가져오기 (예: main)
git pull origin main

# 2) 충돌 해결 후 커밋
git add .
git commit -m "Resolve merge conflicts"

# 3) 푸시
git push

빠른 체크리스트

  • 푸시 실패 시: 먼저 pull로 최신 동기화 했나요?
  • PR 버튼 미노출: 작업 브랜치를 원격으로 푸시했나요?
  • SSH 오류: 로컬 키 생성/등록 및 ssh-agent에 추가했나요?
  • 히스토리 불일치: --allow-unrelated-histories로 병합 후 충돌 해결했나요?
  • 충돌 경고: 충돌 마커 제거 후 커밋하고 다시 푸시했나요?

마무리

이 5가지만 익혀도 PR 과정이 훨씬 수월해집니다. 오류 메시지를 두려워하지 말고, 원인 → 해결 순서로 차근히 대응하세요.
궁금한 점이 있다면 댓글로 남겨 주세요.

댓글남기기

참고