Pull request 생성부터 병합까지

이 글에서는 Pull Request(PR)가 무엇인지, 변경 사항을 논의할 때 어떻게 쓰이는지 알아보고 IDE에서 PR을 만들고 살펴보는 방법을 익힙니다. 좋은 commit을 위한 세 가지 규칙도 함께 다룹니다. Claude Code는 여러분 대신 pull request를 준비하고 댓글을 달 수 있습니다. 이 기능을 제대로 이해하고 쓰려면 PR이 무엇이고 왜 필요한지 알아야 합니다.

예시와 화면 캡처는 JetBrains IDE 기준입니다. 메뉴 이름과 위치는 사용 중인 버전에 따라 다를 수 있습니다. 연습에는 별도의 학습용 저장소를 사용하세요. 실제 프로젝트에서는 해당 프로젝트의 브랜치, 변경 사항 기록, 전송 규칙을 따르세요.

Pull Request가 필요한 이유

팀에서는 변경 사항을 공용 브랜치에 반영하기 전에 함께 검토하는 편이 좋습니다. Pull request는 제안된 diff, 리뷰 의견, 검사 결과를 한곳에 모아줍니다. 개인 프로젝트에서도 병합 전에 자신의 작업을 확인하려고 사용할 수 있습니다.

PR 작업은 먼저 병합 제안을 만드는 데서 시작합니다. GitHub에서는 이를 Pull Request라고 하고, 일부 다른 플랫폼에서는 Merge Request라고 부릅니다. 구체적인 절차는 팀에서 정합니다.

Pull Request는 "제 브랜치의 변경 사항을 가져와(pull) 기본 브랜치에 합쳐(merge) 주세요"라는 공식적인 요청입니다. 하지만 단순한 요청에 그치지 않습니다. 코드가 main에 들어가기 전에 논의하고 검토하고 개선하는 공간이기도 합니다.

Pull Request의 일반적인 작업 흐름

새 기능을 만들 때 보통 어떤 순서로 진행하는지 단계별로 살펴보겠습니다.

브랜치를 만들기 전에 시작 브랜치를 확인하고, GitHub의 대상 브랜치와 비교해 그 브랜치의 commit 목록을 살펴보세요. 새 PR에 관련 없는 로컬 commit이 들어가면 안 됩니다. "동기화"를 위해 무작정 push하지 마세요. 작업에 맞는 기준 브랜치를 선택하고, 기존 작업은 따로 보관하세요.

1단계. 새 작업용 브랜치를 만드세요. 여기서 소개하는 PR 흐름은 별도의 브랜치에서 시작합니다. 기여자를 위한 안내 파일을 추가한다고 가정해 보겠습니다. feature/add-contribution-guide 브랜치를 만드세요.

2단계. 변경 사항을 적용하고 브랜치를 GitHub에 전송하세요. 새 브랜치에서 CONTRIBUTING.md 파일을 만들고 (생성한 다음 Add를 누르세요) 다른 개발자를 위한 안내를 작성합니다. 그런 다음 Commit and Push를 실행하고, 예를 들어 docs: Add contribution guide처럼 명확한 메시지를 입력하세요.

여기가 핵심 단계입니다. Pull Request는 원격 서버에 이미 존재하는 브랜치를 기준으로 만듭니다. 따라서 PR을 만들기 전에 새 브랜치를 반드시 GitHub에 push해야 합니다.

IDE에서 Pull Request 만들기

비교 대상 양쪽을 확인하세요. base는 변경 사항을 반영할 브랜치이고, compare/head는 작업이 담긴 브랜치입니다. PR을 만들기 전에 commit 목록과 diff를 살펴보세요.

브랜치가 GitHub에 올라갔으니 이제 Pull Request를 만들 수 있습니다.

1단계. Pull Requests 탭을 여세요. IDE 왼쪽 사이드바에서 Pull Requests 탭을 찾으세요. 탭을 열고 + 아이콘이나 Create Pull Request 버튼을 누릅니다.

2단계. PR 정보를 입력하세요. IDE에 편리한 입력 화면이 열립니다. 여기서 할 일은 항목을 제대로 채우는 것입니다. 주요 항목은 다음과 같습니다.

1. 제목 - IDE가 브랜치 이름이나 마지막 commit 메시지를 자동으로 채우는 경우가 많습니다. 제목이 간결하고 이해하기 쉬우며 변경 내용을 잘 나타내는지 확인하세요;
2. 설명 - 동료에게 무엇을 했고 왜 했는지 자세히 알려주세요;
3. 리뷰어(Reviewers) - 변경 사항을 검토해 달라고 요청하는 사람입니다. 승인이 필수인지는 저장소 규칙에 따라 달라집니다;
4. 담당자(Assignees) - 보통 작성자인 본인을 지정해 리뷰 후 수정 작업을 맡습니다.

Create Pull Request를 누르기 전에 base, head, diff를 다시 확인하세요. 리뷰받을 준비가 되지 않았다면 가능한 경우 Draft PR을 만들 수 있습니다. 일반 PR과 draft 모두 저장소에 접근할 수 있는 사람에게 표시됩니다.

코드 리뷰 - 검토와 논의

PR을 만든 뒤 가장 중요한 단계인 코드 리뷰가 시작됩니다. 동료가 PR을 열어 모든 변경 사항을 살펴보고 댓글을 남길 수 있습니다.

모든 논의는 IDE의 Pull Requests 탭에서 바로 확인할 수 있습니다. 코드 행에 댓글이 달리면 알림을 받고 브라우저로 전환하지 않고 답할 수 있습니다.

수정을 요청받으면 어떻게 할까요? 간단합니다. 새 PR을 만들 필요는 없습니다. 해당 PR의 원래 브랜치에서 코드를 수정하고 새 commit을 만든 다음 push하세요. 기존 논의에 새 commit이 추가되면서 GitHub의 Pull Request가 자동으로 업데이트됩니다.

작업 마무리 - 병합과 브랜치 삭제

모든 의견을 반영하고 팀이 변경 사항을 승인하면 (즉 "approve"를 받으면) Pull Request를 병합할 수 있습니다. 보통은 시니어 개발자가 진행하며, 저장소 권한이 있다면 직접 할 수도 있습니다.

1단계. 병합. 리뷰 의견, 필수 승인, 검사 상태를 확인하세요. 프로젝트 규칙과 권한이 허용한다면 merge, squash, rebase 중 사용할 수 있는 방식을 선택하고 확인합니다. 변경 사항은 PR의 대상 브랜치에 반영됩니다. 여기서는 main입니다.

2단계. 브랜치 삭제. 병합이 끝나면 feature 브랜치는 더 이상 필요하지 않으므로 저장소를 깔끔하게 유지하도록 삭제하는 편이 좋습니다. GitHub이 Delete branch 버튼으로 삭제를 먼저 제안합니다.

병합 후 로컬에서 main으로 전환해 최신 변경 사항을 가져오고 PR 결과가 반영됐는지 확인하세요. 브랜치에 필요한 작업이 남아 있지 않다면 로컬 작업 브랜치를 삭제해도 됩니다. IDE에서 일반적인 방법으로 삭제할 수 없다면, 특히 squash나 rebase 후에는 먼저 이유를 확인하세요.

좋은 commit을 위한 세 가지 규칙

좋은 commit은 메시지뿐 아니라 내용도 중요합니다. 변경 이력을 깔끔하고 유용하게 남기려면 다음 세 가지 간단한 규칙을 지키세요.

규칙 1 - 의미가 분명한 메시지 작성

commit 메시지는 팀원과 미래의 자신에게 남기는 메모입니다. "fix"나 "update"만 반복되는 이력은 도움이 되지 않습니다. 널리 쓰이는 형식 중 하나인 Conventional Commits는 다음 구조를 제안합니다.

<유형>: <간단한 설명>

유형은 변경 범주를 나타내는 짧은 단어입니다.

• feat - 새로운 기능;
• fix - 오류 수정;
• docs - 문서 변경;
• style - 로직에 영향을 주지 않는 형식 수정;
• refactor - 새 기능을 추가하거나 오류를 수정하지 않는 코드 변경;
• test - 테스트 추가 또는 수정;
• chore - 일상적인 작업 (의존성 업데이트, 빌드 설정).

예시:

• 나쁜 예: fixed bug
• 좋은 예: fix: Correct user login validation
• 나쁜 예: readme
• 좋은 예: docs: Update installation instructions

규칙 2 - 하나의 commit에는 하나의 논리적 변경

버그 수정, 새 기능, 기존 코드 리팩터링을 하나의 commit에 모두 담지 마세요. 그런 commit은 리뷰하기 어렵고, 문제없이 되돌리기도 거의 불가능합니다. 각 commit은 하나의 구체적인 작업을 해결해야 합니다.

• 나쁜 예: 아바타 필드를 추가하고 이름 검증을 수정하며 버튼 색도 바꾸는 "Update user page" commit 하나;
• 좋은 예: 세 개의 commit으로 나누기:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. feat: Update button colors on user page

작업에 몰두하다가 한 파일을 너무 많이 수정했더라도 IDE에서 파일 전체가 아니라 일부만 commit할 수 있습니다. Commit 창에서 파일을 펼친 다음, 해당 작업과 관련된 조각(chunks)에만 체크하세요.

규칙 3 - 변경 결과 확인

병합 전에 변경 사항에 맞는 검사를 실행하고 실제 결과를 확인하세요. 문서 수정과 새 로직에는 서로 다른 검사가 필요합니다.

저장소에 자동 검사가 설정되어 있다면 PR에서 상태를 확인할 수 있습니다. 초록색 표시는 실행된 특정 검사가 통과했다는 뜻이지, 오류가 없다는 증명은 아닙니다. 어떤 검사가 실행됐고 무엇이 아직 확인되지 않았는지 살펴보세요. 자동화 설정은 별도의 주제입니다.

Claude Code와 함께 사용하는 방법

PR은 Claude Code가 특히 유용한 지점입니다. 다음을 확인하세요.

• Claude는 브랜치를 바탕으로 제목과 설명이 채워진 pull request를 만들 수 있습니다. GitHub에서 PR을 생성하기 전에 내용을 확인하세요;
• PR 변경 사항을 검토하고 첫 번째 리뷰어로 댓글을 남길 수 있습니다;
• 프로젝트 규칙에 맞는 commit 메시지 작성을 도와줍니다;
• 이미 설정된 검사 결과를 해석하고 아직 확인되지 않은 항목을 짚어줄 수 있습니다.

이전 글: Git 브랜치와 병합 · 다음 글: Git 변경 사항 취소와 복구