GitHub Stacked PRs로 대규모 PR 리뷰를 병렬화하는 법 (github.github.com)

한줄 요약

GitHub Stacked PRs는 대규모 변경사항을 순서가 있는 PR 체인으로 분리해 리뷰 품질과 머지 속도를 동시에 높이는 네이티브 GitHub 기능이다.

어떤 상황에서 필요한가?

실무에서 PR 크기는 팀의 생산성과 직결된다. 인증 레이어 추가, API 엔드포인트 설계, 프론트엔드 연동까지 한 티켓에 묶인 작업을 단일 PR로 올리는 순간, 리뷰어는 수백 줄의 diff를 마주하게 된다. 이 상황이 반복되면 리뷰 속도가 떨어지고, 피드백 품질도 함께 낮아진다.

문제는 구조적이다. 리뷰어가 컨텍스트를 잃는 게 아니라,애초에 컨텍스트를 파악하기 어렵게 설계된 것이다. 하나의 PR이 너무 많은 관심사를 담고 있기 때문이다.

Stacked PRs는 이 문제를 정면으로 건드린다. 큰 변경사항을 레이어별로 분리하고, 각 PR이 그 아래 PR의 브랜치를 베이스로 삼는 구조를 만든다. 최종적으로 전체 체인이 main에 합류한다. 각 PR은 독립적으로 리뷰 가능하지만, 논리적으로는 하나의 작업 흐름을 이룬다.

현재 이 기능은 Private Preview 단계로, 사용을 원하면 웨이트리스트에 등록해야 한다.

핵심 구현 방법

Stacked PRs의 워크플로는 gh stack CLI를 중심으로 돌아간다. 설치 후 사용 흐름은 다음과 같다.

# CLI 확장 설치
gh extension install github/gh-stack

# 편의를 위한 alias 설정 (선택)
gh stack alias

# 첫 번째 레이어 시작
gs init auth-layer
# ... 커밋 작업 ...

# 다음 레이어 추가
gs add api-routes
# ... 커밋 작업 ...

gs add frontend
# ... 커밋 작업 ...

# 전체 브랜치 푸시 및 PR 생성
gs push
gs submit

gs init으로 스택의 첫 브랜치를 만들고, gs add로 그 위에 레이어를 쌓아간다. gs submit은 올바른 베이스 브랜치 설정과 함께 PR을 일괄 생성한다.

GitHub UI 측에서도 이 구조를 이해한다. 각 PR에는 **스택 맵(stack map)**이 표시되어 리뷰어가 레이어 간 이동을 쉽게 할 수 있고, 브랜치 보호 규칙은 직접적인 베이스 브랜치가 아니라 최종 타겟 브랜치 기준으로 적용된다. CI도 최종 브랜치를 타겟으로 삼는 것처럼 각 PR마다 실행된다.

머지 역시 단순하다. 스택 전체를 한 번에 머지하거나, 특정 레이어까지만 머지할 수 있다. 일부를 머지하면 남은 PR들은 자동으로 리베이스되어, 가장 하위 미머지 PR이 베이스 브랜치를 타겟으로 갱신된다.

AI 에이전트 연동도 지원한다. npx skills add github/gh-stack을 실행하면 AI 코딩 에이전트가 스택 구조를 이해하고 작업할 수 있도록 컨텍스트를 주입할 수 있다.

실전에서 주의할 점

스택 기반 워크플로는 팀 전체가 이해하고 있을 때 효과가 극대화된다. 리뷰어가 스택 구조를 모르면 PR #2를 리뷰할 때 PR #1의 변경사항까지 같이 봐야 하는 게 아닌지 혼란스러워할 수 있다. 온보딩 과정에서 스택 네비게이터 사용법을 공유하는 게 선행되어야 한다.

리베이스 충돌 관리도 현실적인 과제다. 스택의 하위 레이어에서 변경이 생기면 그 위의 레이어들이 순차적으로 영향을 받는다. gh stack이 캐스케이딩 리베이스를 지원하지만, 레이어 간 의존이 깊거나 여러 사람이 같은 스택에서 작업하는 구조라면 충돌 빈도가 올라갈 수 있다.

레이어 분리 기준도 초반에 고민이 필요하다. 너무 잘게 쪼개면 PR 수가 많아져 오히려 관리 부담이 생기고, 너무 크게 묶으면 스택의 이점이 사라진다. 경험적으로는 "하나의 레이어 = 하나의 관심사(concern)" 원칙이 가장 안정적이다.

Private Preview 상태인 만큼 기능 스펙이 바뀔 가능성도 염두에 둬야 한다. 프로덕션 팀 전체에 도입하기 전에 소규모 파일럿 팀으로 먼저 검증하는 접근이 안전하다.