1회차실습 490–115분

Project와 관리 필드

저장소의 이슈 목록은 업무를 번호순이나 갱신순으로 보여 준다. “P0 업무만 위로”, “이번 스프린트만 보드로”, “목표일 순서로 막대그래프”처럼 같은 업무를 다른 기준으로 보려면 업무마다 우선순위, 상태, 날짜 값을 붙일 곳이 필요하다. 이 실습은 GitHub Projects로 관리 화면을 만들고 Priority와 Target date 필드를 추가한다.

진행
설명 5분, 시연 5분, 실습 15분
결과
저장소에 연결된 Project, 필드 2개, LP-01 항목
명령
gh project create, edit, link, field-create, item-add
cd ~/gh-pm-lab
source pm-lab/env.sh

1Project의 소속

Project는 저장소가 아니라 사용자나 조직에 속한다. 그래서 여러 저장소의 이슈를 한 Project에 모을 수 있다. Project를 저장소에 연결(link)하면 저장소의 Projects 탭에서 바로 찾을 수 있지만, 연결만으로 저장소의 이슈가 Project에 들어가지는 않는다. 이슈는 따로 추가해야 한다.

동작결과
Project 생성사용자 계정에 빈 Project가 생긴다. 번호가 붙는다.
저장소 연결저장소 Projects 탭에 Project가 보인다. 이슈는 추가되지 않는다.
항목 추가이슈가 Project의 행으로 들어간다. 이때부터 Status, Priority 값을 붙일 수 있다.

2Project 만들기와 연결

PM_PROJECT=$(gh project create --owner "$PM_OWNER" \
  --title "Launchpad 개발과 출시" --format json --jq .number)
echo "Project 번호: $PM_PROJECT"

gh project edit "$PM_PROJECT" --owner "$PM_OWNER" \
  --visibility PRIVATE \
  --description "M1 비공개 베타와 M2 공개 런칭의 진행 관리"

gh project link "$PM_PROJECT" --owner "$PM_OWNER" --repo "$PM_REPO_NAME"
Project 번호: 3
https://github.com/users/gildong/projects/3
Linked 'gildong/launchpad-pm-lab' to project #3 'Launchpad 개발과 출시'

Project 번호는 계정 안에서 만든 순서대로 붙는다. 이전에 만든 Project가 있으면 1이 아닐 수 있다. 번호를 변수 파일에 저장한다.

echo "PM_PROJECT=\"$PM_PROJECT\"" >> pm-lab/env.sh
tail -n 1 pm-lab/env.sh

3관리 필드 추가

새 Project에는 Title, Assignees, Status, Labels, Milestone 같은 기본 필드가 이미 있다. Status의 기본 선택지는 Todo, In Progress, Done이다. 이 과정에서 정한 Priority와 업무 목표일을 위해 필드 두 개를 더한다.

gh project field-create "$PM_PROJECT" --owner "$PM_OWNER" \
  --name Priority --data-type SINGLE_SELECT \
  --single-select-options "P0,P1,P2"

gh project field-create "$PM_PROJECT" --owner "$PM_OWNER" \
  --name "Target date" --data-type DATE
Created field
Created field
필드유형값의 예
PrioritySINGLE_SELECT (선택지 중 하나)P0, P1, P2
Target dateDATE (날짜)2026-10-14

field-create로 만들 수 있는 유형은 TEXT, SINGLE_SELECT, DATE, NUMBER 네 가지다.

4첫 업무 추가와 확인

gh project item-add "$PM_PROJECT" --owner "$PM_OWNER" --url "$PM_POLICY_URL"
gh project field-list "$PM_PROJECT" --owner "$PM_OWNER" --limit 100
gh project view "$PM_PROJECT" --owner "$PM_OWNER" --web
Added item
NAME                  DATA TYPE                     ID
Title                 ProjectV2Field                PVTF_lAHOA...
Assignees             ProjectV2Field                PVTF_lAHOA...
Status                ProjectV2SingleSelectField    PVTSSF_lAHOA...
...
Priority              ProjectV2SingleSelectField    PVTSSF_lAHOA...
Target date           ProjectV2Field                PVTF_lAHOA...

브라우저의 Project 화면에 LP-01 한 줄이 보인다. 필드 목록의 ID 열은 스크립트에서 쓰는 값이며 이 과정의 명령은 이름을 쓰므로 외울 필요가 없다.

이미 쓰는 Project

다른 사람이 쓰는 Project에서 실습한다면 필드를 새로 만들기 전에 field-list로 이름과 선택지를 먼저 확인한다. Priority가 이미 있으면 새로 만들지 않고, 웹의 필드 설정에서 선택지를 P0·P1·P2로 맞출지 팀과 정한다. 필드 이름은 대소문자를 구분하지 않고 하나만 존재할 수 있다. 선택지는 같은 이름이 둘 이상 생길 수 있으며, 그러면 이름으로 값을 바꾸는 명령이 어느 쪽인지 정하지 못해 실패한다.

  • echo "$PM_PROJECT"가 숫자를 출력하고, pm-lab/env.sh 마지막 줄에 저장되어 있다.
  • 저장소의 Projects 탭에 “Launchpad 개발과 출시”가 보인다.
  • field-list 결과에 Priority와 Target date가 있다.
  • Project 화면에 LP-01이 한 줄 보인다.
막히면
증상확인과 해결
your authentication token is missing required scopes [project]gh auth refresh -s project를 실행하고 브라우저에서 승인한다.
PM_PROJECT가 비어 있음생성은 되었을 수 있다. gh project list --owner "$PM_OWNER" --limit 100으로 번호를 찾아 PM_PROJECT=번호로 직접 지정한다. 생성 명령을 다시 실행하면 같은 이름의 Project가 하나 더 생긴다.
link 실패--repo에는 소유자/ 없이 저장소 이름만 쓴다. $PM_REPO_NAME을 확인한다.
필드가 이미 있다는 오류같은 이름의 필드가 있다. field-list로 확인하고 다음 단계로 넘어간다.

마치며...

사용자 계정에 Project 하나가 생겨 실습 저장소와 연결되었고, Priority와 Target date 필드가 추가되었으며, LP-01이 첫 항목으로 들어갔다. 실습 5에서는 나머지 업무 다섯 개를 파일 목록에서 한 번에 등록한다.