들어가며
요즘 현업에서나 개인, 팀 플젝에서 GitHub를 활용해서 활발하게 PR(Pull Request) 기반 협업을 진행하고있다. 해당 과정에서 작업 브랜치와 동일한 브랜치에서 다른 작업들이 병합이 되면서 충돌(Merge Conflict)이 발생하는 경우가 있다.
물론 IntelliJ IDEA나 vs code를 활용하여 개발 환경 도구를 사용할 수도 있지만, 이러한 충돌을 웹 UI 상에서 간편하게 해결할 수 있다는 점이 GitHub의 장점이라고 필자도 생각하고 있다.
하지만 이번 포스팅은 해당 GitHub 웹에서 Conflict를 해결할때의 주의사항에 대해서 다루어보려고 한다.
이번 글에서는 웹 UI를 통한 충돌 해결 방식이 어떻게 동작하는지, 어떤 주의사항이 있는지, 그리고 충돌 해결 시 권장되는 방식에 대해서 다루어보려고 한다.
Github 웹에서 컨플릭트 해결하는 방법
먼저 컨플릭트에 대해 가벼운 설명이나, 컨플릭트를 최소화 하고싶은 방법이 궁금하다면, 아래 포스팅의 개발 전 고려사항 부분을 봐주어도 좋을거같다. 가치택시 프로젝트를 개발하며 컨플릭트와 관련해서 팀원들과 고민했던 과정이 담겨있다.
가치택시(매칭 알고리즘, Spring)
서론방학이 시작되고 Leets 4기에서 프로젝트를 시작하게 되었고, 내가 참여하여 시작한 프로젝트의 주제는 " 교내 학생들의 택시 이용시, 요금과 시간의 부담을 줄여줄 수 있는 택시 매칭 서비
huncozyboy.tistory.com
다시 돌아와서, 구체적인 컨플릭트 과정부터 살펴보자
공식 GitHub Webhook 설명서
" 동일한 브랜치를 기준으로 다른 브랜치에서 PR을 올렸을 때 같은 파일의 동일한 줄(line) 을 두 브랜치가 수정한 경우에 한해 웹 UI에서 충돌을 해결할 수 있는 옵션이 나옵니다"
https://docs.github.com/articles/about-merge-conflicts?utm_source=chatgpt.com
병합 충돌 정보 - GitHub Docs
병합 충돌은 경합 커밋이 있는 분기를 병합할 때 발생하며 Git가 최종 병합에 통합할 변경 내용을 결정하는 데 사용자의 도움이 필요합니다.
docs.github.com
위 공식문서 내용들을 보면 알 수 있듯이, 서론에서도 설명했듯이 간단하게 컨플릭트를 해결할 수 있다. 좀 더 구체적으론 아래처럼 할 수 있을거같다.
- PR 페이지에서 “This pull request has conflicts that must be resolved” 등의 안내가 뜹니다.
- “Resolve conflicts” 버튼을 클릭하면 충돌이 난 파일별로 편집 화면이 나옵니다.
- < < < < < HEAD, =======, >>>>>>> branch-name 등의 충돌 마커(conflict markers)가 보이고, 원하는 코드만 남기고 마커를 삭제합니다.
- 모든 파일 충돌을 해결하고 나면 “Mark as resolved” → “Commit merge” 등의 버튼이 활성화됩니다.
가장 많이 사용하는 깃허브 전략
이런 귀찮거나 실수가 나올 수도 있는 컨플릭트 상황을 조금이라도 줄이거나, 충돌이 발생했을 때 효율적으로 대응하기 위해서는 브랜치 전략이 굉장히 중요하다고 생각하는데, 필자가 가장 많이 사용하는 깃허브 전략은 github flow이다.
간단하게 설명했을때, 아래 플로우로 진행이 된다
- 기능 별로 브랜치 생성 feat #1 회원가입 기능 구현
- 브랜치로 이동 git checkout -b
- 작업 (새로 생성한 브랜치에서) git add, git commit, git push,
- Pull Request (PR) 생성 간단하게 서로 리뷰
- 메인에다가 머지 리뷰가 끝나면 머지
- 다시 Main 브랜치로 이동 git pull origin main
- 또 새로운 작업 들어가면 1번 반복
GitHub Flow는 비교적 간단하고 직관적인 구조를 가지고 있어서 협업이나 리뷰가 자주 이뤄지는 사이드 프로젝트에서 특히 유용하다고 느꼈다 (개인적인 생각)
본론
서론이 좀 길었는데, 그러면 이 포스팅의 제목인 깃허브 웹 UI를 활용해서 컨플릭트를 해결할시, 어떤 점을 주의해야할까 ?
base 브랜치 전체가 병합될 수 있다.
GitHub 웹 UI에서 Merge Conflict를 해결하면, 단순히 충돌된 파일만 병합되는 것이 아니라 PR의 base 브랜치 전체가 head(compare) 브랜치에 병합된다.
예를 들어, main 브랜치를 기준으로 feature/login 브랜치에서 PR을 만들었고 충돌이 생긴 경우, 웹에서 충돌을 해결하면 main 전체가 feature/login에 병합되는 것이다.
이는 우리가 웹 UI를 사용하지 않고 직접 충돌을 해결할 때를 생각하면 이해가 쉬운데, 기본적으로 웹 UI에서는 head(compare) 브랜치가 base 브랜치의 최신 변경사항을 반영한 뒤 병합되는 방식으로, UI상에서는 “버튼 클릭”으로 간편해 보이기 때문에 이 과정이 눈에 잘 띄지 않을 수 있다고 생각한다.
보통은 흔하게 아래 두가지 두가지 방법을 사용한다.
1. PR을 올린 반대 방향으로 merge하는 케이스
base 브랜치의 변경 사항이 head 브랜치에 반영됩니다. 웹 UI의 동작과 동일합니다.
2. 작업 브랜치를 rebase하는 케이스
마찬가지로 base 브랜치의 변경 사항이 head 브랜치에 반영됩니다.
이 때는 우리가 직접 merge나 rebase를 하면서 base 브랜치의 최신 내용을 반영한다는 사실을 자연스레 인지하는데, 웹 UI에서는 버튼 몇 번으로 간단하게 해결할 수 있다보니 이를 쉽게 간과할 수 있는 것 같다고 개인적으로 생각했다. 그리고 결론적으론 다음과 같은 상황에서는 더 주의해주어야한다.
base 브랜치의 최신 내용을 반영할 시에 주의사항
먼저 필자는 아래 3가지 case를 생각해보았다.
- head 브랜치가 배포 대상인 브랜치일 때
- 충돌 해결 후 커밋 내용이 그대로 유지되어야 하는 경우
- 외부 브랜치나 포크 저장소에서 작업 중일 때
위 3가지의 케이스에서는 단순하게 GitHub 웹 UI에서 Merge Conflict 해결 방식을 사용할때 주의해야된다고 생각했다.
1번 case, 배포 브랜치에 직접적인 변경 이력이 남게 되는 위험이 존재한다.
웹 UI에서 병합을 진행하면 Merge commit이 자동 생성되는데, 이는 CI/CD 파이프라인이 트리거되어 의도치 않게 배포가 재실행될 수도 있다. 또한 병합 과정에서 테스트나 빌드 검증이 충분히 이루어지지 않은 상태로 main이나 release 브랜치에 반영될 수 있다는 점에서도 주의가 필요하다.
3번 case, 포크 저장소나 외부 협업 브랜치에서 권한 문제가 발생할 수 있다.
GitHub 웹 UI에서 병합을 시도하면, 저장소 권한이 제한된 경우 자동 병합이 불가능하거나, 원격 브랜치에 대한 push 권한 부족으로 인해 로컬 변경 사항이 반영되지 않는 문제가 생길 수 있다.
2번 case, 웹 UI 방식에서는 자동으로 병합 커밋이 생성되거나, 커밋 메시지가 시스템 기본값으로 작성되는 경우가 많다.
즉, 히스토리를 깨끗하게 관리해야 하는 프로젝트(예: git log를 통해 변경 흐름을 명확히 추적하거나, git bisect로 디버깅 가능한 상태를 유지해야 하는 경우)라면 웹 UI 방식을 사용하기보다는 로컬에서 명시적으로 커밋 메시지를 작성하고, 필요에 따라 squash 또는 rebase를 통해 이력을 정돈하는 방식을 추천한다.
권장하는 충돌 해결 방식 및 브랜치 전략
GitHub 웹에서 충돌을 해결하기 전, 다음과 같은 점들을 고려하는 것을 권장합니다:
1. 중요한 브랜치는 보호된 브랜치로 설정하기
main, release/* 등 주요 브랜치에 대해 보호 규칙(Protected Branches)을 걸어두는 것이 좋다.
- 직접 push 금지
- force‑push 금지
- 리뷰 승인 필수 등
- 이렇게 하면 실수로 중요한 브랜치를 덮어쓰거나 병합하는 위험을 줄일 수 있음
2. “이 브랜치에 base 브랜치를 통째로 병합해도 괜찮은가?” 사전 검토
head 브랜치에 base 브랜치 전체를 반영해도 문제가 없는가?
→ 만약 head 브랜치가 배포 대상 브랜치이거나, 커밋 히스토리를 깔끔히 유지해야 하는 경우라면 앞서 짧게 설명했듯이 별도로 브랜치를 파서 충돌을 해결하는 편이 안전.
커밋 히스토리가 깔끔하게 유지되어야 하는가?
→ 그렇다면 로컬에서 rebase 혹은 merge --no‑ff 방식으로 해결하는 것이 바람직함.
마치며
간단히 정리하자면, GitHub 웹 UI를 통한 충돌 해결 기능은 편리하지만, 그 내부에서 어떤 동작이 일어나는지, 그리고 너무 쉽게 누르다 보면 의도하지 않은 병합이 발생할 수 있다는 점을 반드시 인지하고 사용하면 더 좋을거같다는 생각에 포스팅을 작성하게 되었다.
참고한 링크
- Resolving a merge conflict on GitHub – GitHub Docs: https://docs.github.com/articles/about-merge-conflicts
- Resolving a merge conflict using the command line – GitHub Docs: https://docs.github.com/articles/resolving-a-merge-conflict-using-the-command-line
- How GitHub merge conflict: How to handle the most common merge conflicts – CloudBees Blog