메타데이터
- 발신자: TLDR
- 원문 URL: https://github.com/github/gh-stack
- 발행일: 2026-08-03
- 카테고리: dev-engineering
직역 전문
GitHub의 스택형 풀 리퀘스트(Stacked PRs)는 대규모 변경 사항을 서로 연결된 여러 개의 작고 리뷰하기 쉬운 풀 리퀘스트의 연쇄로 쪼개는 작업 방식이다. gh stack은 이러한 스택형 브랜치와 풀 리퀘스트를 관리하기 위한 GitHub CLI 확장이다. 이 도구는 브랜치 생성, 리베이스 유지, 올바른 PR 베이스 브랜치 설정, 레이어 간 이동이라는 번거로운 작업들을 자동화한다.
저장소 설명에 따르면 gh-stack의 목적은 "대규모 변경 사항을 서로 위에 쌓이는 작고 리뷰 가능한 풀 리퀘스트의 체인으로 분해"하는 것이다. 개발자는 하나의 거대한 PR을 올리는 대신, 각 PR이 이전 PR 위에 쌓이는 형태로 순차적인 스택을 구성할 수 있다.
핵심 기능
스택 관리
- 여러 브랜치로 구성된 스택을 초기화
- 기존 스택 위에 새 브랜치를 추가
- 모든 레이어에 걸쳐 연쇄적으로 리베이스를 전파
- 스택 구조를 대화형으로 수정(순서 변경, 병합, 삭제)
- 스택 구성과 PR 상태를 조회
워크플로우 자동화
- 로컬과 원격 스택을 한 번의 명령으로 동기화
- 브랜치별 리스(lease) 검사를 거쳐 푸시
- GitHub에 연결된 PR을 제출 및 생성
- 스택 전체를 원자적으로 병합
- 간단한 명령으로 스택 레이어 간 이동
PR 통합
- 로컬 추적 없이 기존 PR을 스택에 연결
- PR 제목과 설명을 자동 생성
.git/gh-stack에 스택 구성을 로컬로 추적
설치
gh extension install github/gh-stack
GitHub CLI v2.0 이상이 필요하다.
주요 명령어
| 명령어 | 목적 |
|---|---|
gh stack init |
새 스택 시작 |
gh stack add |
스택 위에 새 브랜치 생성 |
gh stack push |
원격에 브랜치 푸시 |
gh stack submit |
GitHub에 PR과 스택 생성 |
gh stack rebase |
레이어 전체에 걸친 연쇄 리베이스 |
gh stack sync |
fetch, rebase, push, PR 동기화를 한 번에 수행 |
gh stack merge |
여러 스택형 PR을 원자적으로 병합 |
gh stack modify |
스택을 대화형으로 재구성 |
gh stack checkout |
다른 스택으로 전환 |
탐색 단축 명령으로는 up, down, top, bottom, trunk, switch가 있다.
동작 방식
스택은 순서가 있는 브랜치들로 구성되며, 각 브랜치는 그 아래 브랜치 위에 쌓인다. 스택의 맨 아래 브랜치는 트렁크(일반적으로 main)를 대상으로 하고, 이후의 각 브랜치는 이전 브랜치에 체인처럼 연결된다. 제출 시 브랜치마다 하나의 PR이 생성되며 올바른 베이스 브랜치가 연결되므로, 리뷰어는 해당 레이어의 diff만 볼 수 있다.
로컬 추적 정보는 .git/gh-stack에 JSON 형태로 저장되며, 저장소에 커밋하지 않고도 브랜치 순서와 스택 구성을 관리한다.
AI 에이전트 통합
저장소는 AI 코딩 에이전트를 위한 스킬 설치 방법을 안내한다: gh skill install github/gh-stack. 이를 통해 에이전트가 스택형 PR과 이 CLI 도구를 다루는 방법을 이해하게 된다.
라이선스 및 지원
MIT 라이선스로 배포되며, 행동 강령(code of conduct), 기여 가이드, 보안 정책 문서를 포함하고 있다.
4계층 심층 요약
1. 핵심 주장
gh-stack은 대규모 변경 사항을 하나의 거대한 PR로 올리는 대신, 서로 의존 관계를 가진 여러 개의 작은 PR로 쪼개는 "스택형 PR" 워크플로우를 GitHub CLI 확장으로 자동화한 도구다. 브랜치 생성, 리베이스 유지, PR 베이스 설정, 레이어 간 이동 같은 반복적이고 실수하기 쉬운 작업을 명령어 한두 개로 처리할 수 있게 해 준다.
2. 근거
스택형 PR 방식 자체는 이미 여러 대규모 오픈소스 프로젝트와 빅테크 조직(예: Meta, Google)에서 코드 리뷰 품질과 속도를 높이기 위해 채택해온 검증된 패턴이다. 문제는 이 워크플로우를 수작업으로 유지하려면 브랜치가 늘어날수록 리베이스 충돌, PR 베이스 브랜치 오설정, 스택 순서 관리 등 관리 비용이 기하급수적으로 늘어난다는 점이다. gh-stack은 init, add, push, submit, rebase, sync, merge, modify, checkout 등 명확히 역할이 분리된 명령어 세트와 up/down/top/bottom/trunk/switch 같은 탐색 단축키를 제공함으로써, 이 관리 비용을 프레임워크화된 자동 명령으로 대체한다. 또한 .git/gh-stack에 로컬 상태를 JSON으로 저장해 저장소를 오염시키지 않으면서 스택 구조를 추적하는 설계를 택했다.
3. 사례
예를 들어 개발자가 인증 시스템 리팩터링처럼 규모가 큰 작업을 진행할 때, 이를 "스키마 변경 → 인증 로직 변경 → API 엔드포인트 변경 → 프론트엔드 연동"과 같은 네 단계로 나눠 각각 별도 브랜치로 만들 수 있다. gh stack init으로 스택을 시작하고 gh stack add로 각 레이어를 순서대로 쌓은 뒤, gh stack submit을 실행하면 각 레이어에 대응하는 네 개의 PR이 올바른 베이스 브랜치로 자동 생성된다. 만약 첫 번째 브랜치(스키마 변경)에 리뷰 코멘트를 반영해 수정하면, gh stack sync 한 번으로 나머지 세 개 브랜치가 모두 자동으로 리베이스되고 원격에도 반영된다. 이는 수작업으로 각 브랜치를 순서대로 체크아웃하며 리베이스하는 것보다 훨씬 안전하고 빠르다.
4. 시사점
AI 코딩 에이전트가 대량의 코드를 빠르게 생성하는 시대에는, 오히려 "리뷰 가능한 단위로 변경을 쪼개는" 능력이 더 중요해진다. 에이전트가 한 번에 수백 줄짜리 diff를 만들어내더라도, 사람이 그것을 검토하고 신뢰할 수 있으려면 작고 논리적인 단위로 나뉘어야 하기 때문이다. gh-stack이 gh skill install github/gh-stack 형태로 AI 에이전트 스킬 설치를 지원하는 것은 이런 맥락과 맞닿아 있다. 즉 에이전트가 큰 작업을 수행한 뒤 그 결과를 사람이 리뷰하기 좋은 스택형 PR로 자동 정리해주는 워크플로우가 가능해진다는 뜻이며, 이는 "AI가 만들고 사람이 승인한다"는 하이브리드 개발 프로세스의 인프라 조각으로 자리잡을 가능성이 크다.
핵심 요약 (20줄)
gh-stack은 GitHub CLI를 위한 확장 프로그램으로, 스택형 풀 리퀘스트 워크플로우를 자동화한다.- 스택형 PR이란 하나의 큰 변경 사항을 여러 개의 작고 리뷰하기 쉬운 PR 체인으로 나누는 방식을 말한다.
- 각 PR은 이전 PR 위에 순서대로 쌓이며, 맨 아래 브랜치만
main같은 트렁크를 베이스로 삼는다. - 이 도구는 브랜치 생성, 리베이스 유지, PR 베이스 브랜치 설정, 레이어 간 이동을 자동화해 수작업 부담을 줄인다.
- 설치는
gh extension install github/gh-stack명령으로 간단히 할 수 있으며 GitHub CLI v2.0 이상이 필요하다. gh stack init으로 새로운 스택을 시작할 수 있다.gh stack add는 현재 스택 위에 새로운 브랜치를 추가하는 명령이다.gh stack push는 로컬 브랜치를 원격 저장소로 안전하게 푸시하며, 브랜치별 리스 검사를 거친다.gh stack submit은 GitHub에 연결된 여러 PR을 한 번에 생성해준다.gh stack rebase는 하위 브랜치의 변경 사항을 상위 브랜치들까지 연쇄적으로 반영한다.gh stack sync는 fetch, rebase, push, PR 상태 동기화까지 한 번에 처리하는 종합 명령이다.gh stack merge는 스택 전체의 PR을 원자적으로 병합할 수 있게 해준다.gh stack modify는 스택 구조를 대화형으로 재정렬하거나 브랜치를 접거나 삭제할 수 있게 한다.gh stack checkout으로 여러 스택 사이를 전환할 수 있다.up,down,top,bottom,trunk,switch같은 단축 명령으로 스택 레이어 사이를 빠르게 이동할 수 있다.- 스택 메타데이터는 저장소에 커밋되지 않고
.git/gh-stack에 JSON 형태로 로컬 저장된다. - 기존에 이미 존재하는 PR도 로컬 추적 없이 스택에 연결할 수 있는 기능을 제공한다.
- 저장소는
gh skill install github/gh-stack명령을 통해 AI 코딩 에이전트용 스킬 설치를 지원한다. - 이를 통해 AI 에이전트도 스택형 PR 워크플로우를 이해하고 활용할 수 있게 된다.
- 프로젝트는 MIT 라이선스로 공개되어 있으며, 기여 가이드와 보안 정책 문서도 함께 제공한다.