풀 리퀘스트 (Pull Request)

풀 리퀘스트(Pull Request)는 한 브랜치의 변경을 다른 브랜치에 반영하기 전에 차이와 설명을 제시하고 검토를 요청하는 협업 단위입니다. 보통 PR로 줄여 부릅니다. GitHub에서는 코드 변경에 대한 토론, 리뷰, 검사 결과를 한곳에서 확인하며, 검토가 끝나면 저장소의 규칙에 따라 변경을 병합합니다.

변경 제안과 검토 기록

GitHub의 풀 리퀘스트 설명은 코드 변경을 두고 대화하는 공간으로 PR을 소개합니다. 작성자는 변경한 이유와 확인 방법을 적고, 검토자는 파일의 차이를 읽으며 의견을 남깁니다. 수정이 더 필요하면 같은 작업 브랜치에 커밋을 추가해 제안을 갱신합니다. 파일을 전달하는 것에 더해, 왜 이 변경을 받아들일지 판단할 기록을 함께 남기는 방식입니다.

변경을 가져오는 쪽은 헤드 브랜치, 반영할 대상은 베이스 브랜치라고 부릅니다. 로그인 오류를 고친 작업 브랜치에서 기본 브랜치로 PR을 만들면 두 브랜치 사이의 차이가 검토 대상이 됩니다. 비교 대상을 잘못 고르면 의도하지 않은 파일이나 다른 작업자의 변경까지 목록에 나타날 수 있습니다. 제목만으로 판단하지 않고 실제 차이가 요청한 범위와 일치하는지 읽습니다.

아직 검토를 받을 준비가 끝나지 않았다면 초안 PR로 진행 상황을 공유할 수 있습니다. 초안 상태에서 작업 내용을 논의한 뒤 준비가 되면 검토 가능한 상태로 바꿉니다. PR을 열었다는 사실, 사람이 승인했다는 사실, 변경이 병합됐다는 사실은 각각 다른 상태입니다. 버그 보고를 담는 이슈와도 역할이 달라, 이슈에서 문제를 논의하고 PR에서 그 문제를 해결할 코드 변경을 제안하는 구성이 흔합니다.

승인과 병합 조건

저장소 운영자는 변경을 받아들이는 조건을 정할 수 있습니다. GitHub의 보호된 브랜치 문서는 필수 리뷰와 상태 검사 등의 규칙을 설명합니다. 이 규칙이 적용된 브랜치에서는 정해진 승인이나 검사가 갖춰지기 전까지 병합이 제한됩니다. 모든 저장소가 동일한 조건을 사용하는 것은 아니며 관리 권한과 예외 설정도 결과에 영향을 줍니다.

리뷰 승인은 사람이 변경을 검토한 결과이고, 상태 검사는 연결된 도구가 보고한 실행 결과입니다. 테스트 성공만으로 코드의 의도와 운영 조건까지 검토했다고 볼 수는 없습니다. 반대로 코드 설명에 동의한 리뷰가 있어도 실제 빌드나 테스트가 실패하면 별도로 원인을 확인합니다. 각 결과가 어떤 커밋을 대상으로 했는지 남아 있어야 승인 이후에 추가된 변경도 구분됩니다.

검토 중 코드를 다시 고치면 이전 승인이 그대로 유효한지는 규칙에 따라 달라집니다. 변경된 코드에 대해 새 승인을 요구하도록 설정할 수도 있습니다. 비밀 정보 노출이나 파괴적인 동작처럼 실행 결과만으로 놓치기 쉬운 문제는 파일 차이와 호출 흐름을 직접 읽어 판단합니다. PR 설명에는 실행한 검증과 실행하지 않은 검증을 구별해 적으면 검토자가 확인 범위를 이어받기 쉽습니다.

병합 방식과 배포의 경계

GitHub의 PR 병합 문서는 병합 커밋, 스쿼시 병합, 리베이스 병합을 구별합니다. 병합 커밋은 작업 브랜치의 이력과 합쳐진 지점을 남기고, 스쿼시는 여러 변경을 하나의 커밋으로 묶습니다. 리베이스 병합은 각 변경을 대상 브랜치 위의 새 커밋으로 이어 붙입니다. 같은 파일 내용이 반영되더라도 저장되는 이력의 모습은 달라집니다.

PR을 닫는 행동도 결과를 구분해 읽습니다. 병합하면서 닫은 PR은 제안이 받아들여진 것이고, 병합 없이 닫은 PR은 제안이 중단된 것입니다. 다른 곳에서 같은 변경을 반영했는지는 커밋 이력으로 확인합니다. 작업 브랜치를 지웠다는 사실만으로 코드가 운영 서비스에 적용됐다고 판단할 수는 없습니다.

병합 이후의 배포는 프로젝트가 연결한 별도 절차에 달려 있습니다. 기본 브랜치 변경을 계기로 자동 배포가 시작되는 저장소도 있고, 운영자가 특정 버전을 따로 배포하는 저장소도 있습니다. AI 에이전트가 PR을 만들었다면 제안 생성, 사람의 검토, 병합, 실제 서비스 반영을 각각 추적합니다. 작업 보고에는 실제로 확인한 단계까지 기록합니다.