Community라이팅 & 에디팅github.com

GitHub CLI (`gh`)

GitHub CLI(gh)를 사용하여 저장소, 릴리스, 이슈, PR, 토론, 검색, 코드 리뷰 및 Actions를 명령줄에서 상호작용합니다.

GitHub CLI (`gh`)란 무엇인가요?

이 스킬은 AI 에이전트가 `gh`(GitHub CLI)를 활용하여 GitHub와 명령줄에서 상호작용할 수 있도록 지원합니다. 저장소 조회/복제/읽기, 릴리스 관리, 이슈 및 PR 생성/조회/편집, 댓글 작성, 토론, 검색 등 다양한 GitHub 워크플로우를 포괄합니다. Claude Code, Cursor, Codex 등 AI 코딩 도구와 함께 사용할 때 특히 유용하며, 에이전트가 코드 리뷰, 이슈 트래킹, 코드 검색과 같은 작업을 효율적으로 수행할 수 있게 돕습니다. 스킬 문서는 토큰 효율성, 안전한 작업 처리(쓰기 작업 전 사용자 확인), 그리고 `--json`과 `--jq`를 활용한 데이터 추출 같은 실용적인 가이드라인을 제공하여 AI가 정확하고 안전하게 작업을 수행할 수 있도록 설계되었습니다. 다양한 `gh` 명령어와 플래그를 상세히 다루며, 검색 엔드포인트의 속도 제한이나 복제 vs API 사용 결정과 같은 고급 패턴도 안내합니다.

지원 대상~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add MichaelYochpaz/agent-skills

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

GitHub CLI (gh)

GitHub과 명령줄에서 상호작용: 저장소, 릴리스, 이슈, PR, 토론, 검색, 코드 리뷰 및 Actions.

gh 2.95.0에서 확인됨.

에이전트 가이드라인

  • 알려진 원격 파일이나 디렉토리의 경우 gh repo read-file / gh repo read-dir을 사용하세요(gh 2.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 api with --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"

...

[번역을 위해 잘림]

관련 스킬