GitHub CLI(gh) 사용법 총정리 — 터미널 실전 가이드

Git 명령어로 커밋하고 푸시까지 마쳤는데, Pull Request 하나 만들려면 결국 브라우저를 열어야 합니다. 이슈에 댓글 하나 달려고 GitHub 웹으로 이동하고, Actions 실패 로그를 보려고 또 탭을 바꾸고. 터미널과 브라우저 사이를 끊임없이 왔다 갔다 하는 이 흐름이 번거롭게 느껴진 적 있으신가요? GitHub CLI(gh)는 이런 컨텍스트 전환을 없애고, 터미널 한 곳에서 PR·이슈·Actions까지 모두 처리할 수 있게 해 주는 공식 명령줄 도구입니다.

GitHub CLI(gh)는 GitHub이 공식으로 만든 명령줄 도구입니다. 레포지토리 생성, PR 관리, 이슈 트래킹, Actions 모니터링, 심지어 GitHub REST·GraphQL API 직접 호출까지 터미널 안에서 전부 처리할 수 있습니다. git이 로컬 버전 관리를 담당한다면, gh는 GitHub 플랫폼 위의 모든 협업 기능을 터미널로 끌어오는 도구입니다.

이 가이드에서는 설치부터 인증, 레포지토리·PR·이슈 관리, GitHub Actions 모니터링, 그리고 gh api와 확장(extension)까지 실전에서 바로 쓸 수 있는 명령어를 총정리합니다. 이미 Git에 익숙한 분이라면 gh 하나만 추가하는 것으로 개발 워크플로우가 완전히 달라지는 경험을 하실 수 있습니다.

GitHub CLI란? — Git과 무엇이 다른가

혼동하기 쉽지만 git과 gh는 완전히 다른 도구입니다. git은 리누스 토르발스가 만든 분산 버전 관리 시스템으로, 커밋·브랜치·머지·리베이스 같은 로컬 저장소 작업을 담당합니다. 반면 gh는 GitHub이 2020년에 공식 출시한 CLI 도구로, GitHub 플랫폼의 기능을 터미널에서 조작합니다.

쉽게 비유하면 이렇습니다. git push로 코드를 원격에 올리는 것까지가 git의 영역이고, 올라간 코드를 기반으로 PR을 만들고, 리뷰를 요청하고, 머지하는 것이 gh의 영역입니다. 둘을 조합하면 코드 작성부터 배포까지 브라우저를 한 번도 열지 않고 처리할 수 있습니다.

gh가 커버하는 주요 영역을 정리하면 다음과 같습니다.

• 레포지토리: 생성, 클론, 포크, 목록 조회
• Pull Request: 생성, 체크아웃, 리뷰, 머지, diff 확인
• 이슈: 생성, 목록 조회, 댓글, 닫기, 라벨 관리
• GitHub Actions: 워크플로 실행, 로그 확인, 재실행
• 릴리스: 생성, 다운로드, 삭제
• API: GitHub REST·GraphQL API 직접 호출
• 확장: 커뮤니티가 만든 확장 프로그램 설치·실행

설치 방법 — 3분이면 끝

GitHub CLI는 모든 주요 운영체제를 지원합니다. 본인 환경에 맞는 방법을 하나만 골라서 실행하면 됩니다.

Windows

winget이 가장 간편합니다. PowerShell 또는 Windows Terminal을 열고 아래 명령어를 실행합니다.

winget install GitHub.cli

Scoop을 사용하는 분이라면 scoop install gh, Chocolatey라면 choco install gh로도 설치할 수 있습니다.

macOS

Homebrew 한 줄이면 됩니다.

brew install gh

Linux

Ubuntu/Debian 계열은 GitHub의 공식 APT 저장소를 추가한 뒤 설치합니다.

# 저장소 키 및 소스 추가
(type -p wget >/dev/null || sudo apt install wget -y) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out \
     https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && echo "deb [arch=$(dpkg --print-architecture) \
     signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] \
     https://cli.github.com/packages stable main" \
     | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

Fedora/RHEL 계열은 sudo dnf install gh로 바로 설치 가능합니다.

설치 확인

어떤 방법으로 설치했든, 아래 명령어로 정상 설치를 확인합니다.

gh --version
# 출력 예: gh version 2.65.0 (2026-06-18)

인증 설정 — gh auth login

설치 직후 가장 먼저 해야 할 일은 GitHub 계정 인증입니다. gh auth login 명령어를 실행하면 대화형 프롬프트가 시작됩니다.

gh auth login

프롬프트에서 물어보는 항목은 네 가지입니다.

• GitHub 호스트 선택: GitHub.com 또는 GitHub Enterprise Server. 대부분은 GitHub.com을 선택합니다.
• 프로토콜 선택: HTTPS 또는 SSH. HTTPS가 기본이며, SSH 키를 이미 설정해 둔 분은 SSH를 선택해도 됩니다.
• Git 인증 방식: GitHub CLI의 자격 증명을 Git 작업에도 사용할지 묻습니다. Yes를 선택하면 git push 할 때 별도 인증 없이 바로 됩니다.
• 인증 방법: 브라우저 로그인 또는 토큰 붙여넣기. 브라우저 방식이 가장 편합니다. 8자리 일회용 코드가 터미널에 표시되면 자동으로 열리는 브라우저 페이지에 입력하면 끝입니다.

인증이 완료되면 아래 명령어로 상태를 확인할 수 있습니다.

gh auth status
# 출력 예:
# github.com
#   ✓ Logged in to github.com account your-username
#   - Active account: true
#   - Git operations protocol: https
#   - Token: gho_****
#   - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

토큰의 스코프(권한 범위)가 부족하면 특정 명령어가 실패할 수 있습니다. 예를 들어 workflow 스코프가 없으면 Actions 관련 명령어가 동작하지 않습니다. 이런 경우 gh auth refresh -s workflow로 스코프를 추가할 수 있습니다.

여러 계정 사용

회사 계정과 개인 계정을 동시에 사용해야 한다면, GitHub CLI 2.40부터 도입된 멀티 계정 기능이 유용합니다.

# 두 번째 계정 추가
gh auth login

# 계정 간 전환
gh auth switch

# 현재 활성 계정 확인
gh auth status

레포지토리 관리 — gh repo

GitHub에서 레포지토리를 다루는 모든 작업을 터미널에서 할 수 있습니다.

레포지토리 생성

새 프로젝트를 시작할 때 GitHub 웹에 들어가서 “New repository” 버튼을 클릭할 필요가 없습니다.

# 퍼블릭 레포 생성 (현재 디렉토리 이름 사용)
gh repo create my-project --public

# 프라이빗 레포 생성 + 로컬에 클론까지
gh repo create my-private-app --private --clone

# 대화형 모드 (옵션을 하나씩 물어봄)
gh repo create

대화형 모드에서는 레포 이름, 설명, 공개 범위, .gitignore 템플릿, 라이선스까지 차례로 선택할 수 있어서 처음 사용하기에 편리합니다.

클론과 포크

# 레포지토리 클론
gh repo clone owner/repo-name

# 포크 (내 계정으로 복사) + 로컬 클론
gh repo fork owner/repo-name --clone

# 포크만 하고 클론은 나중에
gh repo fork owner/repo-name

gh repo fork는 포크와 동시에 로컬 Git 리모트를 자동으로 설정해 줍니다. origin은 내 포크, upstream은 원본 레포를 가리키게 되어, 이후 git fetch upstream으로 원본의 최신 변경을 쉽게 가져올 수 있습니다.

레포지토리 조회

# 현재 디렉토리의 레포 정보 (README 포함)
gh repo view

# 특정 레포 정보를 브라우저에서 열기
gh repo view owner/repo-name --web

# 내 레포 목록 (최근 20개)
gh repo list

# 특정 조건으로 필터링
gh repo list --language python --limit 50

gh repo view는 터미널에서 README를 렌더링해 주기 때문에, 오픈소스 프로젝트를 빠르게 훑어볼 때 유용합니다. --web 플래그를 붙이면 기본 브라우저에서 해당 페이지를 열어 줍니다.

Pull Request 완전 정복 — gh pr

GitHub CLI의 꽃은 단연 PR 관리입니다. 브랜치를 만들고 코드를 작성한 뒤, 터미널을 벗어나지 않고 PR 생성부터 머지까지 전 과정을 처리할 수 있습니다.

PR 생성

# 대화형 모드 — 제목, 본문, 리뷰어 등을 차례로 입력
gh pr create

# 커밋 메시지에서 제목과 본문을 자동 채우기
gh pr create --fill

# 모든 옵션을 한 줄에 지정
gh pr create --title "feat: 로그인 기능 추가" \
  --body "OAuth 2.0 기반 소셜 로그인을 구현했습니다." \
  --base main \
  --reviewer teammate1,teammate2 \
  --label enhancement

# Draft PR로 만들기 (아직 리뷰 준비가 안 된 경우)
gh pr create --fill --draft

가장 자주 쓰는 조합은 gh pr create --fill입니다. 마지막 커밋의 제목을 PR 제목으로, 커밋 본문을 PR 설명으로 자동 채워 주기 때문에 커밋 메시지를 잘 작성해 두면 PR 생성이 한 줄로 끝납니다.

PR 목록 조회

# 열려 있는 PR 목록
gh pr list

# 내가 만든 PR만
gh pr list --author @me

# 머지된 PR 보기
gh pr list --state merged --limit 10

# 특정 라벨의 PR
gh pr list --label "bug"

PR 체크아웃과 확인

동료가 올린 PR을 로컬에서 테스트해 보고 싶을 때, gh pr checkout이 매우 편리합니다.

# PR 번호로 체크아웃 — 해당 브랜치를 로컬에 자동 생성
gh pr checkout 42

# PR 상세 정보 확인 (상태, 리뷰, CI 결과)
gh pr view 42

# 변경된 파일의 diff 확인
gh pr diff 42

# 브라우저에서 열기
gh pr view 42 --web

gh pr checkout 42는 내부적으로 원격 브랜치를 페치하고 로컬 브랜치를 만들어 체크아웃까지 해 줍니다. git fetch origin pull/42/head:pr-42 && git checkout pr-42를 한 줄로 줄인 셈입니다.

PR 리뷰

# 승인
gh pr review 42 --approve

# 코멘트만 남기기
gh pr review 42 --comment --body "LGTM, 테스트 추가만 부탁드립니다"

# 변경 요청
gh pr review 42 --request-changes --body "API 응답 형식을 수정해 주세요"

PR 머지

# 기본 머지 (머지 커밋 생성)
gh pr merge 42

# Squash 머지 (커밋을 하나로 합침)
gh pr merge 42 --squash

# Rebase 머지
gh pr merge 42 --rebase

# 머지 후 로컬·원격 브랜치 자동 삭제
gh pr merge 42 --squash --delete-branch

# CI가 모두 통과하면 자동 머지 활성화
gh pr merge 42 --auto --squash

특히 --auto 플래그가 강력합니다. CI 체크가 아직 진행 중이라도 “통과하면 자동으로 머지해 줘”라고 설정해 둘 수 있습니다. 밤에 올린 PR이 새벽에 CI를 통과하면 알아서 머지되는 워크플로우가 가능해집니다.

실전 PR 시나리오: 브랜치 생성부터 머지까지

실제 개발에서 가장 많이 쓰는 흐름을 하나의 시나리오로 정리해 보겠습니다.

# 1. 새 브랜치 생성
git checkout -b feat/user-profile

# 2. 코드 작성 후 커밋
git add .
git commit -m "feat: 사용자 프로필 페이지 구현"

# 3. 푸시
git push -u origin feat/user-profile

# 4. PR 생성 (커밋 메시지로 제목·본문 자동 채우기)
gh pr create --fill

# 5. CI 대기 중 상태 확인
gh pr checks

# 6. CI 통과 후 리뷰 요청
gh pr edit --add-reviewer teammate

# 7. 승인 받으면 squash 머지 + 브랜치 정리
gh pr merge --squash --delete-branch

브라우저를 한 번도 열지 않고 전체 PR 라이프사이클을 처리할 수 있습니다.

이슈 관리 — gh issue

버그 리포트, 기능 요청, 할 일 추적까지 이슈 관리도 터미널에서 바로 할 수 있습니다.

이슈 생성

# 대화형 모드
gh issue create

# 한 줄로 생성
gh issue create --title "버그: 로그인 시 404 에러" \
  --body "Chrome 최신 버전에서 재현됩니다." \
  --label bug,urgent \
  --assignee @me

# 마크다운 파일을 본문으로 사용
gh issue create --title "기능 요청: 다크 모드" --body-file request.md

--body-file 옵션은 긴 이슈를 작성할 때 편리합니다. 에디터에서 마크다운을 충분히 다듬은 뒤 파일째로 넘기면 됩니다.

이슈 조회와 필터링

# 열린 이슈 목록
gh issue list

# 내게 할당된 이슈만
gh issue list --assignee @me

# 특정 라벨 필터
gh issue list --label bug --state open

# 이슈 상세 보기
gh issue view 15

# 브라우저에서 열기
gh issue view 15 --web

이슈 업데이트

# 댓글 달기
gh issue comment 15 --body "#42 PR에서 수정했습니다."

# 이슈 닫기
gh issue close 15

# 이슈 다시 열기
gh issue reopen 15

# 라벨 추가·제거
gh issue edit 15 --add-label "in-progress" --remove-label "triage"

# 담당자 변경
gh issue edit 15 --add-assignee teammate

PR을 머지할 때 커밋 메시지에 Fixes #15를 포함하면 GitHub이 해당 이슈를 자동으로 닫아 줍니다. 이 기능과 gh 명령어를 조합하면 이슈 → 브랜치 → PR → 자동 클로즈까지 매끄러운 흐름이 완성됩니다.

GitHub Actions 모니터링 — gh run · gh workflow

CI/CD 파이프라인이 실패했을 때 로그를 보려고 GitHub 웹으로 이동하는 것도 과거의 일입니다. gh run과 gh workflow로 Actions를 터미널에서 관리할 수 있습니다.

워크플로 실행 상태 확인

# 최근 실행 목록
gh run list

# 특정 워크플로의 실행만 필터링
gh run list --workflow=ci.yml

# 실행 상세 보기 (각 잡의 상태 + 소요 시간)
gh run view 12345678

# 실패한 잡의 로그만 바로 확인
gh run view 12345678 --log-failed

실시간 모니터링

# 실행이 끝날 때까지 실시간 대기 (터미널에 진행 상황 표시)
gh run watch 12345678

gh run watch는 CI가 돌아가는 동안 터미널에서 실시간으로 상태 변화를 보여 줍니다. PR을 올린 뒤 CI 결과를 기다릴 때 유용합니다.

워크플로 수동 실행과 재실행

# 워크플로 목록
gh workflow list

# 수동 트리거 (workflow_dispatch 이벤트가 설정된 경우)
gh workflow run deploy.yml --ref main

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

# 실패한 실행 재실행
gh run rerun 12345678

# 실패한 잡만 재실행
gh run rerun 12345678 --failed

--failed 플래그로 실패한 잡만 골라서 재실행할 수 있어, 전체 워크플로를 처음부터 다시 돌리는 것보다 시간과 비용을 절약할 수 있습니다.

고급 기능 — API 호출, 별칭, 확장

여기까지가 일상적으로 쓰는 명령어의 90%입니다. 이제 활용도를 한 단계 끌어올리는 고급 기능 세 가지를 소개합니다.

gh api — GitHub API 직접 호출

gh api는 GitHub의 REST 또는 GraphQL API를 인증 토큰 걱정 없이 바로 호출할 수 있는 강력한 명령어입니다. cURL에 토큰을 헤더로 넣는 번거로움이 사라집니다.

# 레포지토리 정보 조회 (REST)
gh api repos/owner/repo

# 최근 릴리스 목록
gh api repos/owner/repo/releases --jq '.[].tag_name'

# 페이지네이션 자동 처리 (모든 페이지 가져오기)
gh api repos/owner/repo/issues --paginate --jq '.[].title'

# GraphQL 쿼리
gh api graphql -f query='
  query {
    viewer {
      repositories(first: 5, orderBy: {field: UPDATED_AT, direction: DESC}) {
        nodes { name stargazerCount }
      }
    }
  }
'

--jq 플래그를 사용하면 응답 JSON을 jq 문법으로 바로 필터링할 수 있습니다. 별도로 jq를 파이프할 필요가 없어 한 줄로 원하는 데이터만 추출 가능합니다.

실전에서 특히 유용한 예시를 몇 가지 더 들어 보겠습니다.

# 내 전체 레포의 스타 수 합계
gh api user/repos --paginate --jq '[.[].stargazers_count] | add'

# 특정 PR의 변경 파일 목록
gh api repos/owner/repo/pulls/42/files --jq '.[].filename'

# 최근 14일간 닫힌 이슈 수
gh api search/issues \
  -f q='repo:owner/repo is:issue is:closed closed:>2026-06-19' \
  --jq '.total_count'

gh alias — 자주 쓰는 명령어 줄이기

반복적으로 입력하는 긴 명령어를 짧은 별칭으로 등록할 수 있습니다.

# PR 빠른 생성 별칭
gh alias set prc 'pr create --fill'

# 내 PR 목록 별칭
gh alias set mypr 'pr list --author @me'

# 실패한 CI 로그 바로 보기
gh alias set ci-fail 'run view --log-failed'

# 등록된 별칭 목록
gh alias list

# 사용 예
gh prc          # = gh pr create --fill
gh mypr         # = gh pr list --author @me

별칭은 ~/.config/gh/config.yml에 저장되므로 이 파일을 dotfiles 레포에 포함시키면 어느 머신에서든 동일한 별칭을 사용할 수 있습니다.

gh extension — 커뮤니티 확장

GitHub CLI의 기능을 더 확장하고 싶다면 커뮤니티가 만든 확장 프로그램을 설치할 수 있습니다.

# 대시보드 확장 (PR/이슈를 TUI로 한눈에)
gh extension install dlvhdr/gh-dash

# GitHub Copilot CLI 확장
gh extension install github/gh-copilot

# 설치된 확장 목록
gh extension list

# 확장 업그레이드
gh extension upgrade --all

gh-dash는 특히 추천합니다. 설치 후 gh dash를 실행하면 PR과 이슈를 대시보드 형태의 TUI(Terminal User Interface)로 보여 줍니다. 여러 레포의 PR 상태를 한 화면에서 모니터링할 수 있어 팀 리드나 오픈소스 메인테이너에게 매우 유용합니다.

실전 자동화 — 쉘 스크립트와 조합하기

gh의 진정한 힘은 스크립트 자동화에서 발휘됩니다. 대부분의 gh 명령어는 --json 플래그로 기계 판독 가능한 JSON을 출력하며, --jq로 필터링까지 한 번에 할 수 있습니다.

예제 1: 매일 아침 내 PR 현황 보고

#!/bin/bash
# my-pr-status.sh — 열려 있는 내 PR의 CI 상태를 한눈에 정리

echo "=== 내 PR 현황 $(date +%Y-%m-%d) ==="
echo ""

gh pr list --author @me --json number,title,statusCheckRollup \
  --jq '.[] | "#\(.number) \(.title) [\(
    if (.statusCheckRollup | length) == 0 then "대기"
    elif (.statusCheckRollup | all(.conclusion == "SUCCESS")) then "통과"
    else "실패" end
  )]"'

예제 2: 라벨 기반 이슈 통계

#!/bin/bash
# issue-stats.sh — 라벨별 열린 이슈 수 집계

echo "=== 이슈 통계 ==="
for label in bug enhancement documentation; do
  count=$(gh issue list --label "$label" --state open --json number --jq 'length')
  echo "  $label: ${count}개"
done

예제 3: 릴리스 자동화

#!/bin/bash
# release.sh — 태그 기반 릴리스 생성
VERSION=$1

if [ -z "$VERSION" ]; then
  echo "사용법: ./release.sh v1.2.3"
  exit 1
fi

# 태그 생성 및 푸시
git tag "$VERSION"
git push origin "$VERSION"

# GitHub 릴리스 생성 (최근 태그 이후 커밋 로그를 본문으로)
gh release create "$VERSION" \
  --title "Release $VERSION" \
  --generate-notes

echo "릴리스 $VERSION 생성 완료!"

gh release create의 --generate-notes 플래그는 이전 릴리스 이후의 커밋과 병합된 PR을 자동으로 릴리스 노트에 정리해 줍니다. 수동으로 변경 이력을 작성하는 수고를 크게 덜어 줍니다.

예제 4: 오래된 브랜치 정리

#!/bin/bash
# cleanup-branches.sh — 머지된 PR의 원격 브랜치를 정리

gh pr list --state merged --json headRefName --jq '.[].headRefName' | while read branch; do
  echo "삭제: $branch"
  git push origin --delete "$branch" 2>/dev/null
done

echo "정리 완료!"

자주 쓰는 명령어 빠른 참조 요약

마지막으로 일상 업무에서 가장 많이 쓰는 gh 명령어를 상황별로 정리했습니다. 이 표만 기억해 두면 대부분의 작업을 터미널에서 처리할 수 있습니다.

PR 관련

• gh pr create --fill — 커밋 메시지 기반 PR 빠른 생성
• gh pr list --author @me — 내 PR 목록
• gh pr checkout 42 — PR 브랜치 로컬 체크아웃
• gh pr merge --squash --delete-branch — Squash 머지 후 브랜치 정리
• gh pr merge --auto --squash — CI 통과 시 자동 머지
• gh pr checks — 현재 PR의 CI 상태 확인

이슈 관련

• gh issue create --title "..." — 빠른 이슈 생성
• gh issue list --assignee @me — 내 이슈 목록
• gh issue comment 15 --body "..." — 이슈에 댓글
• gh issue close 15 — 이슈 닫기

Actions 관련

• gh run list — 최근 워크플로 실행 목록
• gh run view --log-failed — 실패한 잡 로그 확인
• gh run watch — 실시간 실행 모니터링
• gh run rerun --failed — 실패한 잡만 재실행

유틸리티

• gh api — GitHub API 직접 호출
• gh alias set — 커스텀 별칭 등록
• gh extension install — 커뮤니티 확장 설치
• gh repo view --web — 현재 레포를 브라우저에서 열기
• gh browse — 현재 브랜치의 GitHub 페이지를 브라우저에서 열기

마무리 — 터미널에서 GitHub 워크플로까지 끊김 없이

GitHub CLI는 이미 Git을 쓰고 있는 개발자에게 가장 자연스러운 생산성 도구입니다. 새 도구를 배우는 것이 아니라, 기존 터미널 워크플로우에 GitHub 기능을 덧붙이는 것이기 때문입니다.

처음부터 모든 명령어를 외울 필요는 없습니다. gh pr create --fill, gh pr list, gh pr merge --squash 이 세 가지만 먼저 습관으로 만들어 보세요. PR 하나 만드는 데 걸리는 시간이 30초에서 5초로 줄어드는 경험을 하면, 자연스럽게 다른 명령어도 찾아 쓰게 됩니다.

어떤 명령어든 기억이 안 나면 gh help 또는 gh pr --help처럼 --help를 붙이면 됩니다. 또한 gh는 명령어를 잘못 입력했을 때 “혹시 이 명령어를 말하는 건가요?”라고 제안까지 해 줍니다.

Git으로 코드를 관리하고, gh로 협업을 관리하면 코드 작성에만 집중할 수 있는 환경이 완성됩니다. 오늘 설치해서 내일 PR부터 터미널에서 만들어 보시기 바랍니다.