수업 전 준비 · PM을 위한 GitHub CLI

1터미널 정하기

이 교안의 명령은 Bash 문법으로 쓰여 있다. Windows의 PowerShell과 명령 프롬프트는 변수 지정, 줄 이어쓰기, 여러 줄 입력 문법이 달라 그대로 붙여넣으면 실패한다.

운영체제	사용할 터미널	비고
macOS	터미널 앱(zsh)	기본 설치되어 있다
Linux	기본 터미널(bash)	기본 설치되어 있다
Windows	Git Bash 또는 WSL	Git Bash는 Git for Windows를 설치하면 함께 생긴다

같은 일을 하는 두 셸의 문법 차이는 다음과 같다.

작업	Bash·zsh (이 교안)	PowerShell
변수 지정	`PM_REPO="me/lab"`	`$PM_REPO = "me/lab"`
변수 사용	`"$PM_REPO"`	`$PM_REPO`
다음 줄에 이어 쓰기	줄 끝의 `\`	줄 끝의 `
여러 줄을 파일로 저장	`cat > f.md <<'EOF'`	`@' ... '@ \| Set-Content f.md`

2GitHub CLI 설치와 버전 확인

설치 방법은 GitHub CLI 공식 설치 안내를 따른다. 대표적인 명령은 다음과 같다.

운영체제	새로 설치	이미 설치되어 있을 때
macOS(Homebrew)	`brew install gh`	`brew upgrade gh`
Windows(winget)	`winget install --id GitHub.cli`	`winget upgrade --id GitHub.cli`
Linux	공식 안내의 배포판별 패키지 저장소 방법을 따른다

Windows에서 설치한 뒤에는 Git Bash 창을 닫고 새로 연다. 열려 있던 창은 새 프로그램 경로를 모른다.

gh --version

gh version 2.102.0 (2026-09-30)
https://github.com/cli/cli/releases/tag/v2.102.0

첫 줄의 버전이 2.97.0 이상이어야 한다. 버전에 따라 쓸 수 있는 명령이 다르다.

버전	이 교안에서 필요한 기능
2.94.0	이슈 의존성(`--add-blocked-by`), 상위 이슈(`--parent`), 이슈 유형(`--type`)
2.97.0	필드 이름으로 Project 값 수정(`item-edit --field --value --url`)
2.102.0	보안 수정 4건. 수업 기준일에 설치 가능한 최신 버전

3Git과 jq 확인

2회차의 PR 실습은 Git으로 문서 하나를 커밋한다. 커밋에는 작성자 이름과 메일이 기록되므로 미리 지정한다. 이미 지정되어 있으면 두 번째와 세 번째 명령은 건너뛴다.

git --version
git config --global user.name "홍길동"
git config --global user.email "gildong@example.com"
git config --global user.name

git version 2.47.0
홍길동

jq는 JSON 파일을 계산하는 도구다. 2회차 실습 12와 3회차의 일정망, EVM 계산, 4회차와 2단계의 이벤트 로그 분석에 쓴다. 설치 예: macOS brew install jq, Windows winget install jqlang.jq, Ubuntu sudo apt install jq.

jq --version

2단계(5·6회차)의 PM4Py 실습은 교안의 웹 실습실에서 한다. 브라우저가 cdn.jsdelivr.net과 pypi.org에 접속할 수 있어야 한다. 회사 네트워크가 막으면 내 컴퓨터의 Python 3.9 이상에 python3 -m pip install pm4py==2.7.23.8을 미리 설치해 둔다. 어느 쪽도 안 되면 교안의 미리 계산한 결과로 진행한다.

4로그인과 project 권한

이미 로그인했다면 첫 명령은 건너뛴다. 로그인 명령은 브라우저를 열고, 터미널에 표시된 8자리 코드를 입력하게 한다.

gh auth login --hostname github.com --git-protocol https --web
gh auth refresh --hostname github.com --scopes project
gh auth setup-git
gh auth status

github.com
  ✓ Logged in to github.com account gildong (keyring)
  - Active account: true
  - Git operations protocol: https
  - Token: gho_************************************
  - Token scopes: 'gist', 'project', 'read:org', 'repo', 'workflow'

명령	하는 일
`gh auth login`	GitHub 계정으로 로그인한다. 기본 권한에는 Project 권한이 없다.
`gh auth refresh --scopes project`	기존 로그인에 `project` 권한을 더한다. Project 생성·수정·조회에 필요하다.
`gh auth setup-git`	Git이 push할 때 gh의 로그인 정보를 쓰도록 설정한다. 2회차 PR 실습에 필요하다.
`gh auth status`	로그인 계정과 권한(Token scopes)을 보여 준다. `'project'`가 있어야 한다.

회사 계정

조직이 SAML SSO를 쓰면 브라우저에서 해당 조직의 토큰 승인을 추가로 요구할 수 있다. 개인 실습은 개인 계정으로 하고, 회사 조직에서 실습하려면 저장소와 Project 생성 권한을 관리자에게 먼저 확인한다.

5작업 폴더와 실습 키트

수업 동안 모든 명령은 같은 작업 폴더에서 실행한다. 작업 폴더를 만들고, 강사가 배포한 실습 키트(github-pm-starter-kit)를 그 안에 압축 해제한다. 키트를 받는 방법은 실습 키트 페이지에 있다.

mkdir -p ~/gh-pm-lab
cd ~/gh-pm-lab
pwd
ls github-pm-starter-kit

/Users/gildong/gh-pm-lab
README.md  backlog.tsv  issues  seed-backlog.sh  sprint-report.sh  templates  weekly-digest.sh

~는 사용자의 홈 폴더다. Git Bash에서는 /c/Users/이름에 해당한다.

6명령 한 줄을 읽는 법

gh 명령은 gh 대상 동작 [인자] [--옵션 값] 순서로 쓴다. 아래 명령은 실습 저장소의 열린 이슈를 최대 100개 보여 준다.

gh issue list -R "$PM_REPO" --state open --limit 100

부분	뜻
`gh`	GitHub CLI 프로그램
`issue`	다룰 대상. 이 밖에 `repo`, `pr`, `project`, `label`, `api` 등이 있다.
`list`	동작. `create`, `view`, `edit`, `close` 등이 있다.
`-R "$PM_REPO"`	대상 저장소. `-R`은 `--repo`의 짧은 형태다. `$PM_REPO`는 셸 변수에 저장한 값으로 바뀐다.
`--state open`	옵션과 값. 열린 이슈만 고른다.
`--limit 100`	최대 개수. 지정하지 않으면 30개까지만 보여 준다.

교안에 자주 나오는 Bash 문법은 다음 다섯 가지다.

문법	예	뜻
변수 지정	`PM_REPO_NAME="launchpad-pm-lab"`	`=` 양옆에 공백을 넣지 않는다.
명령 결과 저장	`PM_OWNER=$(gh api user --jq .login)`	`$( )` 안 명령의 출력이 변수 값이 된다.
줄 이어 쓰기	줄 끝 `\`	다음 줄까지 한 명령이다. `\` 뒤에 공백이 있으면 안 된다.
큰따옴표	`"$PM_MILESTONE"`	값에 공백이 있어도 한 덩어리로 전달한다. 변수는 항상 큰따옴표로 감싼다.
여러 줄 저장	`cat > 파일 <<'EOF'` … `EOF`	두 `EOF` 사이의 줄을 파일에 저장한다. 마지막 `EOF`까지 한 번에 붙여넣는다.

점검

아래 네 명령을 실행해 결과를 확인한다. 세 번째와 네 번째 명령은 해당 옵션이 있는 줄만 보여 준다. 아무것도 출력되지 않으면 gh 버전이 낮다.

gh --version
gh auth status
gh project item-edit --help | grep -E -- '--field |--url '
gh issue edit --help | grep -- '--add-blocked-by'

      --field string                     Name of the field to update
      --url string                       URL of the issue or pull request whose project item to edit
      --add-blocked-by number      Add 'blocked by' relationships by issue number or URL

gh --version이 2.97.0 이상이다.
gh auth status의 Token scopes에 'project'가 있다.
git config --global user.name이 이름을 출력한다.
작업 폴더에서 ls github-pm-starter-kit이 키트 파일을 보여 준다.
점검의 grep 명령 두 개가 각각 옵션 줄을 출력한다.

막히면

증상	확인과 해결
`gh: command not found`	설치 후 터미널을 새로 열었는지 확인한다. Windows는 Git Bash를 다시 연다.
`grep` 결과가 비어 있음	`gh --version`이 2.97.0 미만이다. 2단계의 업그레이드 명령을 실행한다.
Token scopes에 project가 없음	`gh auth refresh --hostname github.com --scopes project`를 다시 실행하고 브라우저에서 승인한다.
브라우저가 열리지 않음	터미널에 표시된 주소를 직접 브라우저에 붙여넣고 코드를 입력한다.
여러 계정에 로그인되어 있음	`gh auth status`에서 Active account를 확인하고, `gh auth switch`로 실습 계정을 고른다.

마치며...

이 페이지를 마치면 터미널에는 project 권한이 있는 로그인 정보가 있고, 작업 폴더에는 실습 키트가 있다. 1회차는 출시 목표와 스프린트를 왜 서로 다른 기능에 두는지에서 시작한다.