홈 / 학습 코스 / Git 완전 정복

12. GitHub CLI (gh) — 터미널에서 GitHub 다루기

🎯 이 장의 목표
  • GitHub CLI(gh)가 무엇이고 git과 무엇이 다른지 이해한다
  • gh를 설치하고 인증(gh auth login)한다
  • 저장소·PR·이슈·릴리스·Actions를 터미널에서 다룬다
  • 브라우저를 오가지 않고 협업 흐름을 완성한다

12.1 git과 gh는 무엇이 다른가?

지금까지 배운 git은 버전 관리 자체를 담당하는 도구입니다(커밋, 브랜치, 병합 등). 하지만 Pull Request, 이슈(Issue), 릴리스, GitHub Actions 같은 것들은 Git의 기능이 아니라 GitHub라는 서비스의 기능입니다. 그래서 지금까지는 이런 작업을 하려면 브라우저로 GitHub에 접속해야 했습니다.

GitHub CLI(gh)는 바로 이 GitHub 고유 기능들을 터미널에서 직접 다루게 해주는 공식 도구입니다.

CODE
git  →  버전 관리 (커밋, 브랜치, 푸시...)        [로컬 + 모든 원격]
gh   →  GitHub 기능 (PR, 이슈, 릴리스, Actions)  [GitHub 전용]
💡 팁
둘은 경쟁 관계가 아니라 짝꿍입니다. git으로 코드를 관리하고, gh로 GitHub 협업을 처리합니다. 브라우저와 터미널을 오가는 "컨텍스트 스위칭"이 사라져 작업이 빨라집니다.
📌 핵심
이 책 기준 최신 버전은 gh 2.94.0(2026년 6월)입니다. gh는 GitHub.com, GitHub Enterprise Cloud, GitHub Enterprise Server 2.20+ 를 지원합니다.

12.2 설치하기

OS명령
Windowswinget install --id GitHub.cli (또는 scoop/choco)
macOSbrew install gh
Ubuntu/DebianGitHub 공식 APT 저장소 등록 후 sudo apt install gh
Fedora/RHELsudo dnf install gh

설치 확인:

BASH
gh --version
CODE
gh version 2.94.0 (2026-06-17)
💡 팁
GitHub Actions의 클라우드 실행 환경(러너 — 작업이 실제로 돌아가는 가상 서버, 자세히는 13_CICD.md)에는 gh가 기본 설치되어 있습니다. 별도 설치 없이 워크플로우 안에서 바로 쓸 수 있습니다.

12.3 인증하기 — gh auth login

gh로 GitHub에 접근하려면 먼저 로그인해야 합니다. 대화형 안내를 따라가면 됩니다.

BASH
gh auth login

질문에 순서대로 답합니다.

CODE
? What account do you want to log into?   → GitHub.com
? What is your preferred protocol...?      → HTTPS
? Authenticate Git with your credentials?  → Yes
? How would you like to authenticate?      → Login with a web browser

브라우저 로그인을 고르면 터미널에 일회용 코드가 표시됩니다. 안내된 URL을 열어 그 코드를 입력하고 권한을 승인하면 끝입니다.

BASH
# 로그인 상태 확인
gh auth status
CODE
github.com
  ✓ Logged in to github.com account yourname (keyring)
  - Git operations protocol: https
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'
💡 팁
CI/CD·자동화용: 사람이 브라우저로 로그인할 수 없는 환경(서버, 파이프라인)에서는 토큰을 직접 넘깁니다.
```bash
echo $GITHUB_TOKEN | gh auth login --with-token
```
📌 핵심
gh auth login 시 "Authenticate Git ... Yes"를 고르면, 5장에서 했던 토큰(PAT) 수동 발급도 gh가 대신 처리해줍니다. push/pull 인증이 자동으로 설정되는 셈이라 입문자에게 특히 편리합니다.

12.4 gh 명령의 기본 구조

CODE
gh <command> <subcommand> [flags]
        │          │          │
      대상       동작        옵션
   (repo,pr,    (create,    (--public,
    issue,run)   list,view)  --web...)

예: gh pr create --web → "PR(대상)을 create(동작)하되 --web(옵션: 브라우저로)"

막힐 땐 언제나 --help:

BASH
gh --help               # 전체 명령 목록
gh pr --help            # pr 관련 명령
gh pr create --help     # pr create 옵션 상세

12.5 저장소 다루기 — gh repo

BASH
# 새 원격 저장소 생성 (대화형)
gh repo create

# 비공개 저장소를 바로 생성하며 현재 폴더와 연결
gh repo create my-project --private --source=. --remote=origin --push

# 저장소 복제 (git clone과 유사하나 OWNER/REPO 축약 가능)
gh repo clone octocat/Hello-World

# 현재 저장소를 브라우저로 열기
gh repo view --web

# 다른 저장소를 내 계정으로 포크
gh repo fork OWNER/REPO --clone
💡 팁
gh repo create ... --source=. --push는 5장에서 했던 "GitHub에서 빈 저장소 만들기 → remote add → 첫 push" 과정을 한 줄로 끝냅니다.

12.6 Pull Request 다루기 — gh pr (핵심!)

부록의 협업 워크플로우에서 "GitHub에서 PR 생성"이라고 했던 부분을 터미널에서 처리할 수 있습니다.

BASH
# 현재 브랜치로 PR 생성 (대화형: 제목/본문 입력)
gh pr create

# 옵션을 직접 지정
gh pr create --base main --head feature/login \
  --title "Add login form" \
  --body "Implements login with basic validation"

# 브라우저에서 PR 작성 폼 열기
gh pr create --web

# 내가 열어둔 PR 목록
gh pr list --author "@me"

# 특정 PR 상세 보기 (번호 또는 URL)
gh pr view 42
gh pr view 42 --comments     # 토론까지

# PR을 로컬에 체크아웃해서 직접 확인/테스트
gh pr checkout 42

# 리뷰 남기기
gh pr review 42 --approve
gh pr review 42 --request-changes --body "Please add tests"

# PR 병합 (방식 선택 가능)
gh pr merge 42 --squash --delete-branch
gh pr merge 옵션의미
--merge일반 병합 커밋 생성
--squash커밋들을 하나로 합쳐 병합
--rebase리베이스 후 병합
--delete-branch병합 후 브랜치 삭제
💡 팁
gh pr checkout 42는 동료의 PR을 내 컴퓨터에서 직접 실행해보며 리뷰할 때 매우 유용합니다. 브랜치 이름을 몰라도 PR 번호만으로 가져옵니다.

12.7 이슈 다루기 — gh issue

BASH
# 이슈 생성 (대화형)
gh issue create

# 옵션 지정 + 라벨/담당자
gh issue create --title "Login button broken" \
  --body "재현 절차: ..." --label bug --assignee "@me"

# 열린 이슈 목록
gh issue list --state open --label bug

# 이슈 상세 보기 / 닫기
gh issue view 17
gh issue close 17
📌 핵심
최신 gh(2.94.0+)는 이슈 타입 지정(--type Bug), 하위 이슈(--parent), 차단 관계 같은 고급 기능도 지원합니다. 입문 단계에서는 create/list/view/close만 익혀도 충분합니다.

12.8 릴리스 다루기 — gh release

11장에서 만든 태그를 GitHub Release로 발행할 수 있습니다.

BASH
# 태그 v1.0.0으로 릴리스 생성 (노트 자동 생성)
gh release create v1.0.0 --generate-notes

# 빌드 결과물(바이너리) 첨부하며 릴리스
gh release create v1.0.0 ./dist/app.zip ./dist/app.exe \
  --title "v1.0.0" --notes "First stable release"

# 릴리스 목록 / 상세
gh release list
gh release view v1.0.0
💡 팁
--generate-notes는 지난 릴리스 이후의 PR·커밋을 모아 릴리스 노트 초안을 자동 작성해줍니다. 수동으로 변경 내역을 정리하는 수고를 덜어줍니다.

12.9 GitHub Actions 다루기 — gh run / gh workflow

다음 장(13장)에서 배울 CI/CD 실행 결과를 터미널에서 모니터링합니다.

BASH
# 최근 워크플로우 실행 목록 (성공/실패/진행중)
gh run list

# 특정 실행 상세 + 로그 보기
gh run view <run-id>
gh run view <run-id> --log

# 실패한 실행을 다시 실행
gh run rerun <run-id>

# 워크플로우 목록
gh workflow list

# 수동 트리거 가능한 워크플로우 실행
gh workflow run deploy.yml --ref main
💡 팁
gh run watch로 진행 중인 실행을 실시간으로 지켜볼 수도 있습니다. PR을 올린 뒤 CI가 통과하는지 터미널에서 바로 확인하는 흐름이 가능합니다.

12.10 편의 기능 — 별칭(alias)과 API

자주 쓰는 명령을 짧게 — gh alias

BASH
# gh prd → 드래프트 PR 생성
gh alias set prd "pr create --draft"

# gh bugs → bug 라벨 이슈 목록
gh alias set bugs "issue list --label bug"

이후 gh prd, gh bugs만 쳐도 됩니다.

무엇이든 자동화 — gh api

gh에 전용 명령이 없는 작업도 GitHub API를 직접 호출해 처리할 수 있습니다.

📌 핵심
API(Application Programming Interface)는 프로그램끼리 대화하는 "창구"입니다. 사람이 웹사이트 버튼을 누르는 대신, 코드가 정해진 형식으로 요청을 보내 GitHub의 기능을 직접 부릴 수 있게 해줍니다.
BASH
# 내 저장소 목록을 JSON으로
gh api user/repos

# 특정 정보만 추출 (--jq)
gh api repos/OWNER/REPO/issues --jq '.[].title'
💡 팁
JSON(JavaScript Object Notation)은 데이터를 { "이름": "값" } 형태로 적는, 사람과 컴퓨터 모두 읽기 쉬운 표준 데이터 형식입니다. 프로그램끼리 정보를 주고받을 때 가장 널리 쓰입니다. 대부분의 gh 명령은 --json 옵션으로 결과를 JSON으로 출력할 수 있어, 스크립트·자동화에 활용하기 좋습니다.

12.11 실습: gh로 PR 협업 끝까지

BASH
# 1. 기능 브랜치에서 작업 후 커밋 (git)
git switch -c feature/greeting
echo "Hello!" > greeting.txt
git add greeting.txt
git commit -m "Add greeting"

# 2. 푸시 + PR 생성을 한 번에 (gh)
git push -u origin feature/greeting
gh pr create --fill          # --fill: 커밋 메시지로 제목/본문 자동 채움

# 3. CI 결과 확인 (gh)
gh pr checks                 # 이 PR의 검사(Actions) 통과 여부

# 4. 리뷰 통과 후 병합 + 브랜치 정리 (gh)
gh pr merge --squash --delete-branch

# 5. 로컬 정리 (git)
git switch main
git pull

브라우저를 한 번도 열지 않고 협업 한 사이클이 끝났습니다.

12.12 이 장에서 배운 것 (요약)

  • git은 버전 관리, gh는 GitHub 기능(PR/이슈/릴리스/Actions)
  • gh auth login으로 인증하면 push 토큰까지 자동 처리
  • 구조: gh <대상> <동작> [옵션], 막히면 --help
  • gh repo(저장소), gh pr(PR), gh issue(이슈), gh release(릴리스), gh run/gh workflow(Actions)
  • gh pr checkout <번호>로 동료 PR을 직접 받아 리뷰
  • gh alias로 단축, gh api로 무엇이든 자동화

✍️ 확인 문제

  1. PR 생성과 이슈 관리는 git이 아니라 왜 gh로 하나요?
  2. 동료의 42번 PR을 내 컴퓨터에서 직접 실행해보려면?
  3. 11장의 태그를 GitHub Release로 발행하는 명령은?
다음 장에서는 push할 때마다 테스트·배포가 자동으로 돌아가는 CI/CD (GitHub Actions)를 배웁니다. → 13_CICD.md