GitHub CLI로 Pull Request 관리

PR을 만들고 CI를 기다리고 리뷰하고 머지하는 흐름은 보통 브라우저 탭을 여러 번 오가게 한다. GitHub CLI(gh)로는 이 과정을 터미널에서 끝낼 수 있다.

설치는 OS별로 다르니 공식 설치 안내를 참고한다(macOS는 brew install gh, Ubuntu/Debian은 sudo apt install gh). 설치 후 인증을 한 번 한다.

gh auth login

브라우저 기반 OAuth가 가장 간단하다. 인증 여부는 다음으로 확인한다.

$ gh auth status
github.com
  ✓ Logged in to github.com account in-jun (keyring)
  - Active account: true
  - Git operations protocol: https
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

1. PR 만들기

먼저 브랜치를 만들고 작업을 push한다.

git checkout -b feature/user-authentication
git add .
git commit -m "feat: implement user authentication logic"
git push -u origin feature/user-authentication

그다음 gh pr create를 실행한다. 옵션 없이 실행하면 제목, 본문, 대상 브랜치를 묻는 대화형 모드가 뜬다. 스크립트나 빠른 작성에는 옵션을 직접 넘긴다.

gh pr create \
  --title "feat: implement user authentication" \
  --body "## Summary
- Add login/logout functionality
- Implement JWT token handling

## Test Plan
- [ ] Unit tests for auth service" \
  --base main \
  --assignee @me \
  --reviewer teammate1,teammate2 \
  --label "enhancement"

자주 쓰는 옵션은 다음과 같다.

작업이 안 끝났으면 초안으로 만들어 두고 나중에 gh pr ready로 전환한다.

gh pr create --draft --title "WIP: refactor payment module"
gh pr ready 123    # 초안 -> 리뷰 준비 완료

2. CI 통과 기다리기

PR을 올린 뒤 gh pr checks로 CI 상태를 본다. 브라우저 새로고침이 필요 없다.

$ gh pr checks 13740
CodeQL                          pass    3s      https://github.com/.../runs/83675225118
CodeQL-Build (go)               pass    3m2s    https://github.com/.../job/83675078092
build (macos-latest)            pass    6m32s   https://github.com/.../job/83675078114
build (ubuntu-latest)           pass    4m38s   https://github.com/.../job/83675078251
integration-tests (ubuntu)      pass    1m33s   https://github.com/.../job/83675078190

--watch는 모든 체크가 끝날 때까지 화면을 갱신하며 기다리고, 하나라도 실패하면 0이 아닌 코드로 종료한다. 스크립트에서 통과했을 때만 다음 단계로 넘어가게 만들 수 있다.

gh pr checks 13740 --watch      # 끝날 때까지 대기
gh pr checks 13740 --fail-only  # 실패한 체크만 보기

내가 관련된 PR 전체 상태는 gh pr status로 본다.

$ gh pr status
Relevant pull requests in in-jun/blog

Current branch
  There is no pull request associated with [main]

Created by you
  You have no open pull requests

Requesting a code review from you
  You have no pull requests to review

3. 남의 PR 리뷰하기

리뷰는 보통 코드를 직접 돌려봐야 한다. gh pr checkout이 PR 브랜치를 로컬로 가져온다.

gh pr checkout 123    # PR 브랜치를 로컬에 체크아웃
git checkout -        # 리뷰 끝나면 원래 브랜치로

diff만 빠르게 볼 때는 터미널에서 바로 본다.

gh pr diff 123

리뷰 제출은 승인, 변경 요청, 코멘트 세 종류다.

# 승인
gh pr review 123 --approve --body "확인했습니다. 잘 작성되었네요."

# 변경 요청
gh pr review 123 --request-changes --body "에러 핸들링 추가가 필요합니다."

# 승인/거절 없이 코멘트만
gh pr review 123 --comment --body "몇 가지 제안이 있습니다."

리뷰어를 나중에 더 붙이거나 라벨을 손볼 때는 gh pr edit을 쓴다.

gh pr edit 123 --add-reviewer myorg/backend-team
gh pr edit 123 --add-label "priority:high" --remove-label "priority:low"

4. 머지

리뷰가 끝나면 머지 전략을 골라 머지한다.

gh pr merge 123 --squash --delete-branch

가장 많이 쓰는 조합이다. squash로 커밋을 하나로 합치고 머지 후 소스 브랜치를 지운다. 다른 전략은 옵션 하나 차이다.

gh pr merge 123 --merge     # 머지 커밋 생성
gh pr merge 123 --rebase    # 대상 브랜치 위에 재적용

CI가 통과하는 순간 바로 머지되게 하려면 --auto를 쓴다. 필수 리뷰와 체크가 모두 통과하면 자동으로 머지된다(저장소에서 auto-merge가 켜져 있어야 한다).

gh pr merge 123 --auto --squash --delete-branch

자주 쓰는 동작은 별칭으로

매번 같은 옵션 조합을 치는 대신 별칭을 만든다.

gh alias set prm 'pr merge --squash --delete-branch'
gh alias set prc 'pr create --draft --assignee @me'

gh prm 123    # squash 머지 후 브랜치 삭제
gh prc        # 초안 PR 생성하고 자신 할당

JSON 출력으로 스크립트에 넘기기

--json과 --jq를 조합하면 PR 데이터를 스크립트에 그대로 넘길 수 있다.

# 열린 PR들의 번호만 추출
gh pr list --json number --jq '.[].number'

# 리뷰 승인된 PR만 골라내기
gh pr list --json number,reviews \
  --jq '.[] | select(.reviews | any(.state == "APPROVED")) | .number'

GitHub Actions 안에서는 GITHUB_TOKEN이 자동으로 잡혀서 별도 인증 없이 쓸 수 있다.

- name: Create PR
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh pr create --title "Auto PR: ${GITHUB_REF_NAME}" \
                 --body "Automated PR" --base main

PR 번호를 생략하면 대부분의 명령이 현재 체크아웃된 브랜치의 PR에 동작한다. 작업 브랜치에 있을 땐 번호를 치지 않아도 된다(gh pr view, gh pr merge).