GitHub CLI (gh)
GitHub과 명령줄에서 상호작용: 저장소, 릴리스, 이슈, PR, 토론, 검색, 코드 리뷰 및 Actions.
gh 2.95.0에서 확인됨.
에이전트 가이드라인
- 알려진 원격 파일이나 디렉토리의 경우
gh repo read-file/gh repo read-dir을 사용하세요(gh2.95에서 미리보기). 구형gh버전이나 API 전용 필요 시, API 패턴의 contents API 폴백을 사용하세요. - 파일 전체 검색이나 경로를 미리 알 수 없는 코드 탐색이 필요한 작업의 경우, 임시 디렉토리에 복제(
gh repo clone owner/repo <temp-dir> -- --depth 1)하고 로컬 파일 읽기 및 검색 도구를 사용하세요. - 읽기/보기에는
--json보다 기본 텍스트 출력을 선호하세요. 토큰 효율성이 더 높습니다. 특정 필드를 프로그래밍 방식으로 추출할 때만--json과--jq를 함께 사용하세요. 지원되는 필드를 확인하려면 필드 목록 없이--json으로 명령어를 실행하고, 필요한 필드만 요청하세요. - 로그나 diff를 볼 때는 먼저 출력 범위를 지정한 후(예:
--name-only,--log-failed) 전체 내용을 가져오세요. - 복제된 저장소 내에서 실행할 때는
--repo플래그가 필요하지 않습니다. 기본적으로 현재 디렉토리의 저장소가 사용됩니다.gh api의 경우 명시적 경로(repos/OWNER/REPO/...)를 사용하거나GH_REPO환경 변수를 설정하세요. - 이 스킬은 명시된 워크플로우에 사용하세요. 필요한 플래그나 필드가 없는 경우, 알 수 없거나 변경된 플래그로 명령어가 실패하는 경우, 또는 명령어가 미리보기로 표시된 경우, 해당 명령어의 도움말을 확인하세요(예:
gh pr diff --help).
안전
- 쓰기 작업(
create,edit,comment,review,close,merge,delete,rerun,run cancel,workflow run/enable/disable, 토론 변경)은 GitHub 상태를 수정합니다. 특히 소유하지 않은 저장소에서 실행하기 전에 사용자에게 확인하세요. - **
gh apiwith--method POST/PUT/PATCH/DELETE**는 쓰기 요청을 보냅니다. 엔드포인트와 페이로드를 다시 확인하세요. 기본 메서드는 GET(안전)이며,-f/-F파라미터를 추가하면 기본값이 POST로 변경됩니다. - 파괴적 작업(
delete,close,merge --admin)은 되돌릴 수 없을 수 있습니다. 명시적인 사용자 확인이 필요합니다.
전제 조건
명령어를 실행하기 전에 gh가 설치되고 인증되었는지 확인하세요:
gh --version
gh auth status
인증되지 않은 경우, gh auth login을 통해 사용자를 안내하세요.
공통 플래그
다음 플래그는 많은 명령어 그룹에서 사용 가능하지만, 명령어에 따라 지원이 다릅니다:
--repo OWNER/REPO-- 다른 저장소를 대상으로 지정합니다(기본값: 현재 디렉토리의 저장소). 전체 URL도 허용됩니다.--json FIELDS-- 지정된 필드로 JSON 출력합니다. 값을 전달하지 않으면 사용 가능한 필드를 나열합니다.--jq EXPRESSION-- jq 구문을 사용하여 JSON 출력을 필터링합니다.--json이 필요합니다.--template STRING-- Go 템플릿을 사용하여 JSON 출력 형식을 지정합니다(--jq의 대안).--web-- 터미널 대신 브라우저에서 리소스를 엽니다.--limit N-- 목록 명령어의 최대 결과 수입니다(기본값은 일반적으로 30).
저장소
보기
저장소의 설명, README, 별표, 언어 분석 및 기타 메타데이터를 표시합니다.
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
복제
저장소를 로컬에 복제합니다. 자동으로 리모트를 구성하고, 포크의 경우 업스트림 리모트를 설정합니다.
gh repo clone owner/repo [target-directory]
원격 저장소 내용 읽기
알려진 파일이나 디렉토리를 빠르게 읽으려면 저장소 읽기 명령어를 사용하세요(gh 2.95에서 미리보기):
# 알려진 파일
gh repo read-file src/main.py --repo owner/repo --ref main
# 알려진 디렉토리
gh repo read-dir src --repo owner/repo --ref main
# 구형 gh 버전을 위한 폴백
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
출력 형태, 파일 크기 제한 및 디렉토리 목록 주의 사항은 API 패턴을 참조하세요. 여러 파일을 탐색하려면 대신 복제하세요(에이전트 가이드라인 참조).
저장소 목록 보기
선택적 언어 및 가시성 필터를 사용하여 사용자나 조직이 소유한 저장소를 나열합니다.
gh repo list owner --limit 30
릴리스
목록 보기
저장소의 릴리스를 생성 날짜 기준으로 나열합니다(최신순). 기본적으로 사전 릴리스 및 초안을 포함한 모든 릴리스를 표시합니다.
gh release list --repo owner/repo --limit 10
플래그:
--exclude-pre-releases-- 사전 릴리스 제외--exclude-drafts-- 초안 제외
주요 JSON 필드: tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable
보기 (변경 로그, 에셋)
릴리스의 변경 로그 본문, 태그, 에셋 및 메타데이터를 표시합니다. 태그를 생략하면 최신 릴리스를 봅니다.
gh release view --repo owner/repo # 최신 릴리스
gh release view v1.2.0 --repo owner/repo # 특정 태그
gh release view v1.2.0 --json tagName,body,assets,publishedAt
주요 JSON 필드: tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url
이슈
목록 보기
저장소의 이슈를 상태, 레이블, 담당자 또는 검색 쿼리로 필터링하여 나열합니다. 기본값은 열린 이슈만 표시합니다.
gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"
플래그:
--state VALUE--open(기본값),closed,all--label NAME-- 레이블로 필터링(여러 개 반복 가능)--assignee LOGIN-- 담당자로 필터링(@me는 자신)--search QUERY-- GitHub 검색 구문
주요 JSON 필드: number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url
보기
이슈의 제목, 본문, 레이블, 담당자 및 상태를 표시합니다. --comments를 사용하여 전체 댓글 스레드를 포함합니다.
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
생성
제목, 본문, 레이블 및 담당자가 있는 새 이슈를 생성합니다.
gh issue create --title "Bug: description" --body "Details..." --label bug --assignee user1
편집
이슈의 제목, 본문, 레이블, 담당자 또는 마일스톤을 업데이트합니다. 모든 플래그를 단일 호출로 결합할 수 있습니다.
플래그:
--title TEXT/--body TEXT-- 제목 또는 본문 업데이트--add-label NAME/--remove-label NAME-- 레이블 수정--add-assignee LOGIN/--remove-assignee LOGIN-- 담당자 수정--milestone NAME/--remove-milestone-- 마일스톤 설정 또는 제거
댓글
기존 이슈에 댓글을 추가합니다.
gh issue comment 123 --body "Comment text"
닫기 / 다시 열기
이슈를 닫거나 다시 엽니다. 선택적으로 닫기 이유를 지정하고 댓글을 남길 수 있습니다.
gh issue close 123 --comment "Fixed in PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
닫기 이유: completed(기본값), not planned, duplicate.
상태
사용자와 관련된 이슈 요약 표시: 사용자에게 할당된 것, 사용자를 언급한 것, 사용자가 연 것.
gh issue status
이슈 유형, 하위 이슈, 상위 관계, 차단 종속성 및 해당 JSON 필드(지원되는 GitHub 호스트 필요)에 대해서는 이슈 참조를 참조하세요.
풀 리퀘스트
이 명령어를 사용하여 PR을 보고 검사하세요. 생성, 병합, 검토 및 PR 관리에 대해서는 풀 리퀘스트 참조를 참조하세요.
목록 보기
저장소의 풀 리퀘스트를 상태, 작성자, 레이블 또는 검색 쿼리로 필터링하여 나열합니다. 기본값은 열린 PR만 표시합니다.
gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot
플래그:
--state VALUE--open(기본값),closed,merged,all--draft-- 초안 상태로 필터링--author LOGIN/--assignee LOGIN-- 작성자 또는 담당자로 필터링--label NAME-- 레이블로 필터링--search QUERY-- GitHub 검색 구문--app NAME-- GitHub 앱 작성자로 필터링(예:dependabot)
주요 JSON 필드: number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url
보기
PR의 제목, 본문, 리뷰 상태, 검사 및 기타 메타데이터를 표시합니다. 인수 없이 현재 브랜치의 PR을 표시합니다. --comments를 사용하여 댓글 스레드를 포함합니다.
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
상태
사용자와 관련된 PR 요약 표시: 현재 브랜치의 PR, 사용자가 생성한 PR, 리뷰가 요청된 PR.
gh pr status
토론
저장소 토론에 gh discussion을 사용하세요(gh 2.94에서 미리보기). 읽기 명령어로 시작하고 명령어 세트가 미리보기이므로 --help로 플래그를 확인하세요:
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
생성, 편집, 댓글, 답글 스레드, JSON 출력 형태 및 GraphQL 폴백 패턴에 대해서는 토론 참조를 참조하세요.
검색
이슈, PR, 코드, 커밋 및 저장소에 대해 GitHub 전체를 검색합니다. 단일 저장소에는 gh issue list / gh pr list를 사용하고, 저장소 간 또는 소유자 전체 쿼리에는 gh search ...를 사용하세요.
전체 검색 쿼리 구문은 GitHub 검색 문서를 참조하세요. 각 하위 명령어별 플래그는 gh search <subcommand> --help를 실행하세요.
속도 제한: 검색 API는 핵심 API보다 더 엄격한 속도 제한이 있습니다. 코드 검색이 가장 제한적입니다(인증 시 약 10회/분, 인증 필요). 다른 검색 명령어는 인증 시 약 30회/분 또는 미인증 시 약 10회/분을 허용합니다. 현재 할당량은 gh api rate_limit --jq '.resources | {search, code_search}'로 확인하세요.
언제 복제할까요: API 대신 복제해야 하는 시기는 에이전트 가이드라인을 참조하세요.
봇 및 앱: Dependabot과 같은 GitHub 앱 작성자의 경우 --app dependabot을 사용하세요. --author dependabot은 사용자 계정을 필터링하며 앱 작성자는 필터링하지 않습니다.
정찰: 익숙하지 않은 저장소를 검색할 때 먼저 기본 언어를 확인하여 올바른 --extension 및 --language 값을 선택하세요:
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
이슈
키워드, 레이블, 상태 또는 GitHub 검색 구문을 사용하여 저장소 전체에서 이슈를 검색합니다.
gh search issues "error handling" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo
주요 플래그: --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.
PR
저장소 전체에서 풀 리퀘스트를 검색합니다. 작성자, 리뷰 상태, 병합 상태 및 초안 상태별 필터링을 지원합니다.
gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo
주요 플래그: --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.
코드
GitHub 저장소 전체에서 파일 내용을 검색합니다. 일치하는 줄만 반환합니다(줄 번호 없음, 주변 컨텍스트 없음). 패턴이 포함된 파일을 찾는 데 유용하지만, 코드 로직을 이해하려면 파일 읽기로 후속 조치를 취하거나 저장소를 복제하세요.
제한 사항: 레거시 검색 엔진을 사용합니다(결과가 github.com과 일치하지 않을 수 있음). 기본 브랜치만 검색합니다. 384KB 미만의 파일만 인덱싱됩니다. 모든 쿼리에는 하나 이상의 검색어가 포함되어야 합니다(한정자 전용 검색(예: --extension ts 단독)은 실패합니다). --sort 또는 --order를 지원하지 않으며, 결과는 항상 관련성 순으로 정렬됩니다.
gh search code "functionName" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json
주요 플래그: --repo, --owner, --extension, --filename, --language, --match, --size.
주요 JSON 필드: path, repository, sha, textMatches, url.
textMatches 필드는 문자 수준의 일치 위치와 함께 조각 컨텍스트를 제공합니다. 기본 텍스트 출력보다 더 많은 컨텍스트가 필요할 때 --json path,textMatches를 사용하세요.
커밋
커밋 메시지 텍스트, 작성자, 커미터 날짜 또는 해시로 커밋을 검색합니다.
gh search commits "fix bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
주요 플래그: --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.
저장소
키워드, 언어, 주제, 별표, 라이선스 또는 소유자별로 저장소를 검색합니다. 참고: 이 하위 명령어에서는 --repo를 사용할 수 없습니다. 소유자별로 필터링하려면 --owner를 사용하세요.
gh search repos "keyword" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
주요 플래그: --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.
한정자 제외(하이픈 접두사)
-label:bug와 같은 제외가 포함된 검색 쿼리는 셸 플래그 해석을 피하기 위해 특별한 구문이 필요합니다. 모든 플래그(예: --limit)는 -- 앞에 와야 합니다. -- 뒤의 모든 것은 검색 쿼리 텍스트로 해석됩니다:
# Unix 계열 셸
gh search issues -- "my query -label:bug"
# PowerShell
gh --% search issues -- "my query -label:bug"
...
[번역을 위해 잘림]