GitHub CLI (gh) 스킬
gh CLI를 사용하여 터미널에서 GitHub 저장소, 이슈, 풀 리퀘스트, GitHub Actions 워크플로우와 상호작용합니다.
사전 요구 사항
gh가 설치되고 인증되었는지 확인합니다:
gh --version
gh auth status
인증되지 않은 경우 gh auth login을 실행하고 프롬프트를 따릅니다.
핵심 워크플로우
이슈 관리
# 이슈 목록
gh issue list # 현재 저장소의 열린 이슈
gh issue list --state all # 닫힌 이슈 포함 전체
gh issue list --assignee @me # 나에게 할당된 이슈
gh issue list --label "bug" # 레이블로 필터링
# 이슈 생성
gh issue create -t "제목" -b "설명"
gh issue create -t "제목" --label "bug,priority:high" --milestone "milestone-1"
gh issue create # 대화형 모드
# 이슈 조회/수정
gh issue view 123 # 이슈 세부 정보 보기
gh issue view 123 --web # 브라우저에서 열기
gh issue edit 123 --add-label "in-progress"
gh issue close 123
gh issue reopen 123
# 댓글 추가
gh issue comment 123 -b "지금 작업 중입니다"
브랜치 및 커밋 워크플로우
# 기능/수정 브랜치 생성
git checkout -b feature/my-feature
git checkout -b fix/issue-123
git checkout -b draft/wip-experiment
# 변경 사항 스테이징 및 커밋
git add .
git commit -m "feat: 새 기능 추가"
git commit -m "fix: 이슈 #123 해결"
# 브랜치를 원격으로 푸시
git push -u origin feature/my-feature
풀 리퀘스트 관리
# PR 생성 (여러 방법)
gh pr create # 대화형 모드
gh pr create --fill # 커밋 메시지로 자동 채우기
gh pr create --draft # 드래프트로 생성
gh pr create --draft --fill # 자동 채우기 드래프트
gh pr create -t "제목" -b "설명" -B main
gh pr create --label "review-needed" --assignee @me
# PR 목록
gh pr list # 열린 PR
gh pr list --assignee @me # 내 PR
gh pr list --search "review-requested:@me" # 내 리뷰 요청된 PR
gh pr list --draft # 드래프트 PR만
# PR 세부 정보 보기
gh pr view 45 # 터미널에서 PR 보기
gh pr view 45 --web # 브라우저에서 열기
코드 리뷰 워크플로우
# 테스트를 위해 로컬에서 PR 체크아웃
gh pr checkout 45 # PR 브랜치를 로컬로 체크아웃
# 변경 사항 검토
gh pr diff 45 # PR diff 보기
gh pr diff # 현재 브랜치 PR의 diff
# 리뷰 댓글 추가
gh pr comment 45 -b "LGTM, 42번 줄에 사소한 제안"
gh pr comment -b "테스트를 추가해 주세요" # 현재 브랜치 PR에 댓글
# 공식 리뷰 제출
gh pr review 45 --approve
gh pr review 45 --request-changes -b "오류 처리를 수정해 주세요"
gh pr review 45 --comment -b "전반적으로 좋습니다. 몇 가지 제안"
# 병합
gh pr merge 45 # 대화형 병합
gh pr merge 45 --squash # 스쿼시 병합
gh pr merge 45 --rebase # 리베이스 병합
gh pr merge 45 --merge # 표준 병합 커밋
gh pr merge 45 --auto # 검사 통과 시 자동 병합
기존 PR 업데이트
gh pr edit 45 --title "새 제목"
gh pr edit 45 --body "업데이트된 설명"
gh pr edit 45 --base develop
gh pr edit 45 --add-label "ready-for-review"
gh pr ready 45 # 준비 완료 표시 (드래프트 해제)
GitHub Actions 워크플로우 관리
# 워크플로우 실행 목록
gh run list # 최근 워크플로우 실행
gh run list --workflow=ci.yml # 특정 워크플로우
gh run list --status=failure # 실패한 실행만
# 워크플로우 실행 세부 정보 보기
gh run view # 대화형 실행 선택기
gh run view 12345 # 특정 실행
gh run view 12345 --web # 브라우저에서 열기
# 워크플로우 트리거
gh workflow run ci.yml # 기본 브랜치에서 실행
gh workflow run ci.yml --ref feature/x # 특정 브랜치에서 실행
gh workflow run ci.yml -f key=value # 입력 매개변수 포함
# 실패한 작업 재실행
gh run rerun 12345 # 모든 작업 재실행
gh run rerun 12345 --failed # 실패한 작업만 재실행
# 작업 로그 보기
gh run view 12345 --log # 전체 로그 출력
gh run view 12345 --log-failed # 실패한 작업 로그만
# 진행 중인 실행 감시
gh run watch # 현재 실행 감시
gh run watch 12345 # 특정 실행 감시
공통 플래그 참조
| 플래그 | 설명 |
|---|---|
-R, --repo OWNER/REPO | 다른 저장소 대상 지정 |
-B, --base | PR의 기본 브랜치 |
-H, --head | PR의 헤드 브랜치 |
-t, --title | 이슈/PR 제목 |
-b, --body | 이슈/PR 본문/설명 |
-l, --label | 레이블 (쉼표로 구분) |
-a, --assignee | 담당자 사용자명 |
-m, --milestone | 마일스톤 이름 |
--draft | 드래프트 PR로 생성 |
--fill | 커밋 메시지로 자동 채우기 |
--web | 브라우저에서 열기 |
-y, --yes | 확인 프롬프트 건너뛰기 |
환경 변수
export GH_TOKEN="ghp_xxxx" # 개인 액세스 토큰
export GH_HOST="github.example.com" # GitHub Enterprise 인스턴스
export GH_REPO="owner/repo" # 기본 저장소
팁 및 주의 사항
마크다운을 사용한 여러 줄 설명
코드 블록이나 백틱이 포함된 긴 설명으로 이슈나 PR을 생성할 때, 셸 해석 문제로 실패할 수 있는 히어독(heredocs)을 피하세요. 대신:
# 1단계: 설명을 임시 파일에 작성 (bash 외부에서)
# 2단계: 임시 파일에서 생성
gh issue create -t "제목" -b "$(cat temp_description.txt)"
# 3단계: 정리
rm temp_description.txt
이렇게 하면 다음 문제를 피할 수 있습니다:
- 명령어 대체와 충돌하는 코드 블록의 백틱
- 셸에 의해 해석되는 특수 문자
- 히어독 구분자 충돌
기존 파일에서 설명 가져오기
마크다운 계획 파일에서 이슈나 PR을 생성하려면:
# 깔끔한 파일 기반 설명을 위해 body-file 플래그 사용
gh issue create -t "제목" --body-file docs/plans/my-plan.md
gh pr create -t "제목" --body-file docs/plans/my-plan.md
자세한 참조
포괄적인 명령 옵션과 예제는 references/commands.md를 참조하세요.