GitHub CLI

주의 사항 (Anti-patterns)

1. gh api 사용 금지

# ❌ gh api - 임의의 REST/GraphQL 엔드포인트 호출 가능 (권한 제어 불가)
gh api repos/{owner}/{repo}/issues
gh api graphql -f query='{ viewer { login } }'

# ✅ 구체적 서브커맨드 사용 (allowed-tools로 권한 제한 가능)
gh issue list
gh pr list
gh release list

gh api는 모든 GitHub API 엔드포인트에 접근할 수 있어 allowed-tools로 특정 동작만 허용하는 것이 불가능하다. gh issue, gh pr 등 구체적 서브커맨드를 사용하면 Bash(gh issue:*) 형태로 세밀한 권한 제어가 가능하다.

2. Write 작업 무단 수행 금지

# ❌ 사용자 확인 없이 Write 작업 수행
gh issue create --title "Bug fix" --body "Fixed it"
gh pr merge 123
gh issue close 456

# ✅ 사용자에게 먼저 확인 후 수행
# "이슈를 생성할까요? 제목: Bug fix, 본문: Fixed it"
# → 사용자 승인 후 실행
gh issue create --title "Bug fix" --body "Fixed it"

이슈 생성, PR 병합, 코멘트 작성 등 외부에 영향을 미치는 Write 작업은 반드시 사용자에게 내용을 보여주고 확인을 받은 뒤 수행한다.

3. 현재 디렉토리에서 불필요한 git -C 사용

# ❌ 현재 디렉토리가 대상 레포지토리인데 -C 옵션 사용
git -C /path/to/current/repo log --oneline

# ✅ 현재 디렉토리에서 바로 실행
git log --oneline

현재 디렉토리가 작업 대상 레포지토리와 동일하면 git -C 옵션은 불필요한 중복이다. 다른 경로의 레포지토리를 대상으로 할 때만 사용한다.

4. 하드코딩된 레포지토리 정보

# ❌ 레포지토리 정보 하드코딩
gh issue list --repo DaleStudy/skills

# ✅ 현재 디렉토리의 Git 원격 정보 활용 (기본값)
gh issue list

gh CLI는 현재 디렉토리의 Git 원격 정보를 자동으로 감지한다. --repo 플래그는 다른 레포지토리를 대상으로 할 때만 사용한다.

Read vs Write 명령어 분류

Read (안전 - 자유롭게 실행 가능)

명령어	설명
gh issue list	이슈 목록 조회
gh issue view {number}	이슈 상세 조회
gh issue view {number} --comments	이슈 코멘트 조회
gh issue status	관련 이슈 상태 요약
gh pr list	PR 목록 조회
gh pr view {number}	PR 상세 조회
gh pr view {number} --comments	PR 코멘트 조회
gh pr status	관련 PR 상태 요약
gh pr diff {number}	PR 변경사항 조회
gh pr checks {number}	PR CI 상태 확인
gh release list	릴리스 목록 조회
gh release view {tag}	릴리스 상세 조회
gh label list	레이블 목록 조회
gh repo view	레포지토리 정보 조회
gh search issues {query}	이슈 검색
gh search prs {query}	PR 검색
gh run list	워크플로우 실행 목록 조회
gh run view {run-id}	워크플로우 실행 상세 조회
gh run view {run-id} --log	워크플로우 실행 로그 조회
gh run view {run-id} --log-failed	실패한 스텝 로그만 조회
gh workflow list	워크플로우 목록 조회
gh workflow view {name|id}	워크플로우 상세 조회

Write (사용자 확인 필수)

명령어	설명
gh issue create	이슈 생성
gh issue close {number}	이슈 닫기
gh issue reopen {number}	이슈 다시 열기
gh issue edit {number}	이슈 수정
gh issue comment {number}	이슈에 코멘트 작성
gh pr create	PR 생성
gh pr merge {number}	PR 병합
gh pr close {number}	PR 닫기
gh pr reopen {number}	PR 다시 열기
gh pr edit {number}	PR 수정
gh pr comment {number}	PR에 코멘트 작성
gh pr review {number}	PR 리뷰 제출
gh release create {tag}	릴리스 생성
gh release delete {tag}	릴리스 삭제
gh label create {name}	레이블 생성
gh label edit {name}	레이블 수정
gh label delete {name}	레이블 삭제
gh run rerun {run-id}	워크플로우 재실행
gh run cancel {run-id}	워크플로우 실행 취소
gh workflow run {name|id}	워크플로우 수동 실행 (workflow_dispatch)
gh workflow disable {name|id}	워크플로우 비활성화
gh workflow enable {name|id}	워크플로우 활성화

이슈 관리 모범 사례

이슈-PR 연결

# PR 본문에 키워드로 이슈 자동 연결 (PR 병합 시 이슈 자동 닫힘)
gh pr create --title "Fix login bug" --body "Closes #123"

연결 키워드: Closes, Fixes, Resolves (대소문자 무관)

라벨 체계

# 라벨 목록 확인
gh label list

# 라벨로 이슈 필터링
gh issue list --label bug
gh issue list --label "good first issue"

이슈 검색

# 담당자별 이슈
gh issue list --assignee @me

# 상태별 이슈
gh issue list --state open
gh issue list --state closed

# 조합 검색
gh issue list --label bug --assignee @me --state open

Pull Request 모범 사례

PR 생성

# 기본 PR 생성
gh pr create --title "Add user authentication" --body "## Summary
- JWT 기반 인증 구현
- 로그인/로그아웃 API 추가

## Test Plan
- [ ] 로그인 성공/실패 테스트
- [ ] 토큰 만료 시 갱신 테스트"

# Draft PR 생성 (리뷰 준비가 안 된 경우)
gh pr create --draft --title "WIP: Add user authentication"

# 리뷰어 지정
gh pr create --reviewer user1,user2 --title "Add feature"

PR 크기 가이드

• 변경된 파일 수: 10개 이하 권장
• 변경된 라인 수: 400줄 이하 권장
• 하나의 PR은 하나의 목적만 달성
• 크면 나누기: 리팩토링과 기능 추가를 별도 PR로 분리

PR 리뷰

# PR 변경사항 확인
gh pr diff 123

# PR CI 상태 확인
gh pr checks 123

# PR 리뷰 승인
gh pr review 123 --approve

# PR 리뷰 코멘트
gh pr review 123 --comment --body "전반적으로 좋습니다. 몇 가지 제안사항이 있습니다."

# PR 변경 요청
gh pr review 123 --request-changes --body "인증 로직에 보안 문제가 있습니다."

PR 병합

# Squash merge (커밋 히스토리 정리, 권장)
gh pr merge 123 --squash

# Merge commit
gh pr merge 123 --merge

# Rebase merge
gh pr merge 123 --rebase

# 병합 후 로컬/원격 브랜치 자동 삭제
gh pr merge 123 --squash --delete-branch

릴리스 관리

시맨틱 버저닝

• MAJOR (v2.0.0): 하위 호환성이 깨지는 변경
• MINOR (v1.1.0): 하위 호환 가능한 기능 추가
• PATCH (v1.0.1): 하위 호환 가능한 버그 수정

릴리스 생성

# 릴리스 노트 자동 생성
gh release create v1.0.0 --generate-notes

# 제목과 본문 지정
gh release create v1.0.0 --title "v1.0.0" --notes "첫 번째 안정 릴리스"

# 프리릴리스
gh release create v2.0.0-beta.1 --prerelease --generate-notes

# Draft 릴리스 (바로 공개하지 않음)
gh release create v1.0.0 --draft --generate-notes

릴리스 조회

# 최신 릴리스 확인
gh release view --repo {owner}/{repo}

# 릴리스 목록
gh release list

# 특정 릴리스 상세
gh release view v1.0.0

워크플로우 실행 및 결과 조회

실행 결과 확인

# 최근 워크플로우 실행 목록
gh run list

# 특정 워크플로우만 필터링
gh run list --workflow ci.yml

# 실행 상세 정보 (상태, 소요 시간, 트리거 등)
gh run view {run-id}

# 실패한 스텝의 로그만 확인 (디버깅에 유용)
gh run view {run-id} --log-failed

# 전체 로그 확인
gh run view {run-id} --log

워크플로우 수동 실행

# workflow_dispatch 이벤트가 설정된 워크플로우 실행
gh workflow run ci.yml

# 입력 파라미터 전달
gh workflow run deploy.yml -f environment=staging -f version=1.2.0

# 특정 브랜치에서 실행
gh workflow run ci.yml --ref feature/my-branch

실패 대응

# 실패한 job만 재실행
gh run rerun {run-id} --failed

# 전체 재실행
gh run rerun {run-id}

# 진행 중인 실행 취소
gh run cancel {run-id}

주요 gh 서브커맨드 레퍼런스

gh issue

gh issue list [--state open|closed|all] [--label name] [--assignee handle]
gh issue view {number} [--comments]
gh issue create --title "제목" --body "본문" [--label name] [--assignee handle]
gh issue close {number} [--reason completed|not_planned]
gh issue reopen {number}
gh issue edit {number} [--title "새 제목"] [--add-label name] [--remove-label name]
gh issue comment {number} --body "코멘트"
gh issue status

gh pr

gh pr list [--state open|closed|merged|all] [--label name] [--author handle]
gh pr view {number} [--comments]
gh pr create --title "제목" --body "본문" [--draft] [--reviewer handle]
gh pr merge {number} [--squash|--merge|--rebase] [--delete-branch]
gh pr close {number}
gh pr reopen {number}
gh pr edit {number} [--title "새 제목"] [--add-label name] [--add-reviewer handle]
gh pr comment {number} --body "코멘트"
gh pr review {number} [--approve|--comment|--request-changes] [--body "리뷰"]
gh pr diff {number}
gh pr checks {number}
gh pr status

gh release

gh release list
gh release view {tag}
gh release create {tag} [--title "제목"] [--notes "노트"] [--generate-notes]
gh release delete {tag} [--yes]

gh label

gh label list
gh label create {name} [--color hex] [--description "설명"]
gh label edit {name} [--name "새이름"] [--color hex] [--description "설명"]
gh label delete {name} [--yes]

gh repo

gh repo view [--web]
gh repo clone {owner}/{repo}

gh run

gh run list [--workflow name] [--status completed|in_progress|failure|success]
gh run view {run-id} [--log] [--log-failed]
gh run rerun {run-id} [--failed]
gh run cancel {run-id}
gh run watch {run-id}

gh workflow

gh workflow list
gh workflow view {name|id}
gh workflow run {name|id} [-f key=value] [--ref branch]
gh workflow disable {name|id}
gh workflow enable {name|id}

gh search

gh search issues {query} [--repo owner/repo] [--state open|closed]
gh search prs {query} [--repo owner/repo] [--state open|closed|merged]