GitHub Stacked PR 알아보기, 의존성 있는 작업을 작은 PR로 나누어 관리

기존 PR을 할때 항상 느끼던 문제점을 해결할 수 있는 Stacked PR걸 알아보려고한다.

 

그런말이 있다. PR을 할때 코드는 200~300줄이 가장 좋다고

그런데 작업을 진행하다보면 큰 기능 같은 경우에는 200줄 300줄이 넘어가기도 하며 이렇게 되면 코드리뷰를 할 때 항상 문제가 되기도 한다. 코드리뷰를 하면서 오랜 시간이 걸리기도하고 그게 반복되면 효율성이 떨어져 코드리뷰단계가 점점 생략되어가는 경험도 한적이 있다.

 

 

기존 PR 방식 문제점 (Pain Points)

큰 단위의 기능을 개발할 때 코드 리뷰를 위해서 PR을 작게 쪼개는것들이 권장되지만 실제 워크플로우에서는 다음과 같은 한계점들이 있다.

• 의존성이 있는 연쇄 작업
  • 앞선 작업이 merge되어야 다음 작업의 PR을 제대로 올릴 수 있기 때문에 리뷰 완료 전까지 개발 흐름이 끊길 수 있다.
  • 이를 해결하기위해 rebase를 통한 불필요한 반복하며 관리하는일이 생긴다.
• 리뷰 대기중 > 다른작업 > 수정, 충돌
  
  • 리뷰를 기다리기 싫어서 다른 브랜치에서 작업을 하다 보면 기존 PR에 수정이나 merge가 일어날 때마다 하위 브랜치까지 수동 Rebase와 충돌 해결(Conflict Resolution)을 반복하게 된다.
  • 가장 큰 문제점이라고 생각한다. 브랜치가 꼬이는 부분들이 있다면 rebase를 통해 연결, 관리만 해주면 되지만 다른 브랜치에서 작업중이였다면 stash를 통해 작업을 멈추고 이전 브랜치 수정사항을 반영하고 충돌된 부분을 해결하고.. 불필요한 시간들이 너무 많다.
• 점점 커지는 PR 단위
  • rebase 관리가 번거로워 결국 하나의 브랜치에 코드를 밀어넣게 된다거나 이전 작업들을 또 fetch 및 적용후 PR을 하게 되면 많은 코드량이 겹치기도하며 맥락을 찾기 힘들기도하다. 리뷰 속도는 느려진다. 

 

---

GitHub Stacked PR

 

- Stacked PR은 순서대로 의존성을 가지는 작은 PR들을 계층(Stack)처럼 쌓아 올리는 작업 방식이다.

- GitHub에서 최근 Public Preview로 공개하며 써드파티 도구 없이 GitHub CLI 및 Web UI에 네이티브로 통합되었다.

 

주요 구성 및 동작 원리

• 독립적인 Layer 리뷰
  • 전체 기능 중 레이어(단계)별 Diff만 따로 떼어서 개별 PR로 검토할 수 있다.
• Stack Map 제공
  • PR상단에 시각적인 Stack Map이 표시되어 전체 기능 중 현재 검토하는 PR이 어느 위치인지 한눈에 확인 가능
• 병렬 리뷰 지원
  • 팀원들이 각 레이어별 PR을 동시에 병렬로 리뷰하더라도 개발 흐름이 블로킹되지 않는다.

 

 

---

핵심 기능 정리 및 실사용 정리

1. 단 한번의 클릭으로 전체/부분 merge
   1. 준비된 최상위 PR을 merge하면 그 밑의 아직 머지 되지 않은 하위 PR들까지 한번의 클릭으로 일괄 merge할 수 있다.
   2. 스택의 하위 레이어만 먼저 merge하면 상위 PR들은 자동으로 Rebase되고 타겟 브랜치가 변경된다.
2. 기존 Branch Protection 및 Merge Queue 지원
   1. Stacked PR을 사용해도 기존의 CI/CD체크, 리뷰 승인 조건 등 기존 Branch Protection Rule이 그대로 적용 됨
   2. Merge Queue와 결합하여 5개 이상의 Stacked PR을 한번에 안정적으로 main 브랜치로 반영시킬 수 있다.
3. CLI 및 툴링 생태계 지원
   1. Github 확장 프로그램(gh-stack)을 제공하여 터미널에서도 간편하게 스택을 생성하고 관리할 수 있다.

gh extension install github/gh-stack

 

 

 

 

 

- github web ui로도 관리하며 stack list로 한눈에 볼 수 있다.

- 작업단위에 맞게 볼 수 있기 때문에 흐름도 끊기지 않고 리뷰를 할때에도 큰 어려움 없이 가능하다.

 

 

 

- 순차적으로 merge를 시키면서 스택을 쌓을 수 있고 관리가 가능

 

 

---

초기 세팅 및 실행 흐름 정리(Stacked PR 워크플로우)

 

1. 초기 환경 세팅

- Stacked PR을 사용하기 위해선 Github CLI 확장 프로그램을 설치하고 메인 브랜치를 최신화 해야한다.(dev면 dev 최신화)

# GitHub CLI 확장 프로그램 설치 (최초 1회)
gh extension install github/gh-stack

# 작업할 메인 브랜치로 이동 및 최신화
git checkout main
git pull origin main

 

 

2. 리뷰 대기 없이 브랜치 연속으로 쌓기 (Stacking)

- 하위 레이어 PR이 머지될 때까지 기다릴 필요가 없다.

- gh stack create 명령어를 통해서 이전 작업 브랜치 바로 위에 다음 작업 브랜치를 잇달아 쌓아 올린다.

# [Layer 1] DB 모델 작업 브랜치 생성 및 커밋
gh stack create feature/1-models
git add .
git commit -m "feat: add user database model"

# [Layer 2] API 작업 브랜치 생성 (Layer 1을 기반으로 쌓임)
gh stack create feature/2-api
git add .
git commit -m "feat: implement user creation API"

# [Layer 3] UI 작업 브랜치 생성 (Layer 2를 기반으로 쌓임)
gh stack create feature/3-ui
git add .
git commit -m "feat: add user creation form UI"

 

 

3. Stack 제출 및 상태 확인

- 작업이 완료되면 명령어 하나로 쌓여 있는 모든 브랜치를 개별 PR로 한 번에 푸시하고 등록한다.

# 로컬에 쌓은 모든 Stack 브랜치와 PR을 GitHub에 한 번에 제출
gh stack submit

# 현재 스택의 계층 구조와 PR 리뷰 진행 상태 확인
gh stack status

 

 

 

4. 중간 레이어 수정 및 자동 Rebase (Sync)

- 코드 리뷰 중 하위 레이어에 수정 요청이 들어오면 해당 브랜치로 이동 후 코드를 수정하고 sync를 실행하면 상위 브랜치들까지 자동으로 Rebase 처리 된다.

# 리뷰 피드백 반영을 위해 Layer 1 브랜치로 이동
gh stack checkout feature/1-models

# 코드 수정 후 커밋
git add .
git commit -m "fix: update user model validation"

# 수정 사항을 상위 스택(Layer 2, 3)에 자동으로 Rebase 반영
gh stack sync

# 변경된 스택 정보 GitHub에 업데이트 Push
gh stack submit

 

 

 

5. 전체 Stack 일괄 merge

- 모든 레이어의 리뷰와 CI 체크가 통과되면 최상위 브랜치에서 일괄 머지 명령을 실행해 스택 전체를 main 브랜치에 안전하게 반영한다.

# 스택의 최상단(Layer 3)으로 이동
gh stack checkout feature/3-ui

# 하위에 연결된 모든 PR을 포함하여 main 브랜치로 일괄 머지
gh stack merge --land