GitHub Issues 완전 가이드: Epic, Sub-Issues, Labels로 프로젝트를 체계적으로 관리하는 법

1. GitHub Issues, 아직도 버그 리포트용으로만 쓰시나요?

많은 개발자가 GitHub Issues를 "버그 발견 → 이슈 등록 → 수정 → 닫기" 정도의 흐름으로만 사용합니다. 하지만 GitHub Issues는 프로젝트 전체의 로드맵, 태스크 관리, 팀 협업을 아우르는 강력한 도구입니다.

특히 2025년부터 GitHub는 Issues 시스템을 대폭 강화했습니다:

• Sub-Issues (하위 이슈): 이슈 간 부모-자식 계층 구조
• Issue Types (이슈 유형): 조직 레벨에서 bug, task, feature 등 분류
• 향상된 Projects 통합: 로드맵 뷰, 자동화 워크플로우

이 글에서는 GitHub Issues를 제대로 활용하는 방법을 실전 예시와 함께 정리합니다.

2. GitHub Issues의 핵심 기능 총정리

먼저 개별 기능부터 하나씩 살펴보겠습니다.

2.1 이슈(Issue)의 기본 구조

하나의 이슈는 다음 요소로 구성됩니다:

2.2 Labels (라벨)

라벨은 이슈를 분류하고 필터링하는 태그입니다.

기본 제공 라벨

GitHub는 새 리포지토리에 9개의 기본 라벨을 제공합니다:

커스텀 라벨 만들기

기본 라벨만으로는 부족합니다. 프로젝트에 맞는 커스텀 라벨을 만들어보세요.

CLI로 라벨 생성:

# 단일 라벨 생성
gh label create "open-core" --color "6f42c1" --description "Open-Core 전환 관련"

# 이미 있으면 업데이트
gh label create "open-core" --color "6f42c1" --description "Open-Core 전환 관련" --force

# 여러 라벨 한번에 (쉘 스크립트)
for phase in 0 1 2 3 4 5; do
  gh label create "phase:$phase" --color "5ab0cd" --description "Phase $phase"
done

웹 UI로 라벨 생성:

Issues 탭 → Labels 버튼 → New label → 이름, 설명, 색상 입력 → Create label

라벨 네이밍 전략

효과적인 라벨은 카테고리:값 형태로 네이밍하면 좋습니다:

# 유형별
type:bug          type:feature       type:refactor

# 우선순위별
priority:critical  priority:high      priority:low

# 상태별
status:blocked     status:in-review   status:ready

# 영역별
area:frontend      area:backend       area:infra

# 단계별
phase:0            phase:1            phase:2

이렇게 하면 label:phase:1처럼 네임스페이스 기반 필터링이 가능해집니다.

2.3 Milestones (마일스톤)

마일스톤은 마감일이 있는 이슈 그룹입니다.

Milestone: v1.0 Release (마감일: 2026-04-01)
├── #12 feat: 로그인 구현        ✅ closed
├── #13 feat: 회원가입 구현      ✅ closed
├── #14 feat: 비밀번호 재설정    🔴 open
└── #15 fix: 세션 만료 처리      🔴 open
                                ━━━━━━━━━ 50% 완료

마일스톤은 진행률 바를 자동으로 보여줍니다. 이슈가 닫힐 때마다 진행률이 올라가는 방식이에요.

마일스톤 vs 라벨 — 언제 뭘 써야 할까요?

팁: 둘 다 쓰세요. 마일스톤으로 시간축을 관리하고, 라벨로 분류하면 됩니다.

#42 feat: DB 추상화 레이어
  - Milestone: v2.0 Release
  - Labels: enhancement, phase:1, area:backend

2.4 Pinned Issues (고정 이슈)

리포지토리의 Issues 탭 최상단에 이슈를 고정하는 기능입니다.

• 최대 3개까지 고정 가능
• write 권한이 있는 사용자만 고정/해제 가능
• 이슈 목록 위에 카드 형태로 표시됨

고정 방법:

# CLI
gh issue pin 38

# 웹 UI
이슈 열기 → 오른쪽 사이드바 → "Pin issue" 클릭

해제 방법:

# CLI
gh issue unpin 38

# 웹 UI
고정된 이슈 열기 → 오른쪽 사이드바 → "Unpin issue" 클릭

어떤 이슈를 고정할까요?

3개라는 제한이 있으므로 신중하게 선택해야 합니다:

2.5 Issue Types (이슈 유형) — 2025 신기능

2025년에 GA(General Availability)된 기능입니다. 조직(Organization) 레벨에서 이슈 유형을 정의합니다.

기본 제공 유형:

커스텀 유형 (최대 25개):

Organization Settings → Planning → Issue types에서 추가할 수 있습니다.

Epic          큰 작업 단위, 하위 이슈 포함
Spike         조사/리서치 작업
Tech Debt     기술 부채 해결

이슈 유형 vs 라벨 — 뭐가 다른가요?

정리하면 — Type은 이슈의 정체성, Label은 이슈의 속성입니다.

3. Sub-Issues (하위 이슈) — 게임 체인저

2025년 4월 GA된 가장 중요한 기능입니다. 기존에는 체크리스트(Task List)로 대체하던 것을 이제 공식적으로 이슈 간 부모-자식 관계로 관리할 수 있습니다.

3.1 Sub-Issues란?

#100 Epic: 인증 시스템 구축        ← 부모 이슈 (Parent)
  ├── #101 DB 스키마 설계          ← 하위 이슈 (Sub-Issue)
  ├── #102 로그인 API 구현
  ├── #103 회원가입 UI
  └── #104 세션 관리

핵심 특징:

• 하위 이슈는 일반 이슈와 동일합니다. 부모가 할당된 것일 뿐이에요
• 부모 이슈당 최대 50개 하위 이슈
• 최대 8단계 중첩 가능
• 크로스 리포지토리 지원 (다른 리포의 이슈도 하위로 연결 가능)
• 부모 이슈에 진행률 자동 표시

3.2 Sub-Issues 만들기

웹 UI:

1. 부모가 될 이슈를 엽니다
2. 이슈 본문 아래의 "Sub-issues" 섹션에서 "+" 버튼 클릭
3. 기존 이슈를 검색하여 추가하거나, 새 이슈를 바로 생성

기존 이슈에 부모 설정:

1. 자식이 될 이슈를 엽니다
2. 오른쪽 사이드바 → "Parent issue" → 부모 이슈 검색/선택

3.3 Tasklist → Sub-Issues 마이그레이션

2025년 4월 30일부로 기존 Tasklist(체크리스트 블록)은 폐기되었습니다.

기존 방식 (Tasklist — 더 이상 작동 안 함):

- [ ] #101 DB 스키마 설계
- [ ] #102 로그인 API 구현
- [ ] #103 회원가입 UI

새 방식 (Sub-Issues):

이슈 본문에 체크리스트를 작성하는 대신, 이슈의 "Sub-issues" UI를 통해 공식적으로 연결합니다.

기존 Tasklist 블록은 일반 마크다운으로 변환되었습니다. 아직 이 방식을 사용하고 계시다면 Sub-Issues로 전환하세요.

3.4 Sub-Issues 검색 필터

# 하위 이슈가 있는 이슈만
has:sub-issues-progress

# 부모 이슈가 있는 이슈만 (= 누군가의 하위 이슈)
has:parent-issue

# 조합
has:sub-issues-progress label:open-core

3.5 Sub-Issues가 없던 시절의 대안: 체크리스트 패턴

Sub-Issues를 사용할 수 없는 환경(GitHub Enterprise Server 구버전 등)에서는 마크다운 체크리스트 + 이슈 번호 참조 패턴을 사용할 수 있습니다:

## 구현 체크리스트

- [ ] Phase 0: 오픈소스 릴리스 준비 — #31
- [ ] Phase 1: DB 추상화 레이어 — #32
- [ ] Phase 2: 에디션 시스템 — #33
- [ ] Phase 3: 인증 시스템 — #34
- [ ] Phase 4: 멀티테넌시 — #35
- [ ] Phase 5: UI 통합 — #36

이 방식은 체크는 수동이지만, 이슈 번호가 자동 링크되므로 클릭 한 번으로 이동할 수 있습니다. 해당 이슈가 닫히면 취소선이 자동으로 그어지기도 합니다.

4. Epic Issue 패턴 — 큰 그림 관리하기

4.1 Epic이란?

Epic은 여러 이슈를 묶는 상위 이슈입니다. GitHub에 "Epic" 기능이 따로 있는 건 아니지만, 이슈를 Epic처럼 활용하는 패턴이 널리 사용됩니다.

#38 Epic: Open-Core 전환               ← Epic (상위)
  ├── #31 Phase 0: 라이선스/문서          ← 하위 이슈
  ├── #32 Phase 1: DB 추상화
  ├── #33 Phase 2: 에디션 시스템
  ├── #34 Phase 3: 인증
  ├── #35 Phase 4: 멀티테넌시
  ├── #36 Phase 5: UI 통합
  └── #37 Phase 6: Docker 배포

4.2 좋은 Epic 이슈의 구조

# Epic: [프로젝트/기능 이름]

## 개요
왜 이 작업이 필요한지 (2-3문장)

## 아키텍처 결정
| 결정 | 선택 | 근거 |
|------|------|------|
| 인증 | Better Auth | Organization 플러그인 내장 |
| DB | PostgreSQL + SQLite | 듀얼 지원 필요 |

## Phase 체크리스트
- [ ] Phase 0: 기초 작업 — #31
- [ ] Phase 1: 인프라 — #32
- [ ] Phase 2: 핵심 기능 — #33
- [ ] Phase 3: UI — #34

## 검증 시나리오
1. 시나리오 A: ...
2. 시나리오 B: ...

핵심 포인트:

• 개요에 "왜"를 명확히 적으세요. 3개월 후 다시 봐도 맥락을 이해할 수 있어야 합니다
• 아키텍처 결정은 대안 비교 테이블로. "왜 이걸 선택했는지"를 기록해두면 나중에 "왜 이렇게 했지?"라는 질문에 바로 답할 수 있습니다
• 체크리스트에 이슈 번호를 넣으면 클릭으로 바로 이동할 수 있습니다
• Epic은 Pin해두세요 — Issues 탭에서 항상 최상단에 보입니다

4.3 Epic vs 마일스톤 — 뭘 써야 할까?

추천 조합:

Milestone: v2.0 Release (마감일: 2026-06-01)   ← "언제까지"
  └── Epic: #38 Open-Core 전환                  ← "무엇을, 왜"
        ├── #31 Phase 0
        ├── #32 Phase 1
        └── ...

마일스톤으로 시간을 관리하고, Epic으로 범위와 맥락을 관리하세요.

5. 효과적인 이슈 본문 작성법

5.1 나쁜 이슈 vs 좋은 이슈

나쁜 이슈:

# 로그인 기능 추가

로그인 기능을 추가해주세요.

이슈를 보고 바로 작업에 들어갈 수 없습니다. 어떤 방식으로? 어떤 라이브러리로? 뭘 검증해야 하는지?

좋은 이슈:

# feat: 인증 시스템 구축 (Better Auth)

## 배경
SaaS 모드에서 사용자 인증과 조직 관리를 제공하기 위한 인증 시스템.
Better Auth 라이브러리를 사용하며, OSS 모드에서는 완전히 비활성화된다.

## 아키텍처 결정
| 라이브러리 | Next.js 16 호환 | 조직 관리 | 선택 이유 |
|-----------|:-:|:-:|------|
| Better Auth | ✅ | 내장 | Prisma 어댑터 지원 |
| NextAuth v5 | ⚠️ | 없음 | 호환성 이슈 |

## 구현 상세
### 생성할 파일
- `src/lib/auth/index.ts` — 서버 설정
- `src/app/api/auth/[...all]/route.ts` — API 핸들러

### 수정할 파일
- `prisma/schema.prisma` — User, Session 모델 추가
- `src/app/layout.tsx` — AuthProvider 래핑

## 의존성
- 선행: #32 (DB 추상화)
- 후행: #35 (멀티테넌시)

## 검증
- [ ] `EDITION=oss` → 로그인 페이지 404
- [ ] `EDITION=saas` → 로그인/회원가입 동작
- [ ] 세션 유지 확인

## 참고
- Better Auth 문서: https://www.better-auth.com/docs
- 폼 패턴 보일러플레이트: `src/components/projects/project-form.tsx`

5.2 이슈 본문 템플릿

프로젝트에 맞는 이슈 템플릿을 만들어두면 일관성을 유지할 수 있습니다.

기능 요청 (Feature Request)

## 배경
(왜 이 기능이 필요한지, 어떤 문제를 해결하는지)

## 아키텍처 결정
(기술 선택과 근거 — 대안 비교 테이블 권장)

## 구현 상세
### 생성할 파일
- `파일 경로` — 역할, 핵심 구현 포인트

### 수정할 파일
- `파일 경로` — 변경 내용, Before/After 예시

## 의존성
- 선행: #이슈번호 (설명)
- 후행: #이슈번호 (설명)

## 검증
- [ ] 테스트 시나리오 1
- [ ] 테스트 시나리오 2

## 참고
- 보일러플레이트 파일: `경로`
- 외부 문서: URL

버그 리포트 (Bug Report)

## 증상
(무엇이 잘못되고 있는지)

## 재현 방법
1. Step 1
2. Step 2
3. 예상: ...
4. 실제: ...

## 환경
- 브라우저/OS:
- 버전:

## 관련 코드
- `파일 경로:라인` — 의심되는 원인

## 스크린샷
(있으면 첨부)

GitHub Issue Template 설정

.github/ISSUE_TEMPLATE/ 디렉토리에 YAML 파일을 만들면 이슈 생성 시 자동으로 템플릿이 적용됩니다:

# .github/ISSUE_TEMPLATE/feature_request.yml
name: Feature Request
description: 새 기능 요청
labels: ["enhancement"]
body:
  - type: textarea
    id: background
    attributes:
      label: 배경
      description: 왜 이 기능이 필요한가요?
    validations:
      required: true
  - type: textarea
    id: implementation
    attributes:
      label: 구현 상세
      description: 어떻게 구현할지 설명해주세요
  - type: textarea
    id: verification
    attributes:
      label: 검증 방법
      description: 어떻게 테스트할 수 있나요?

5.3 이슈 간 상호 참조

GitHub에서 #번호를 쓰면 자동으로 해당 이슈/PR에 링크됩니다. 이 기능을 적극 활용하세요.

## 의존성
- 선행: Phase 1 (DB 추상화) — #32
- 후행: Phase 4 (멀티테넌시) — #35

참조된 이슈 쪽에서도 "이 이슈가 #34에서 언급됨"이라는 알림이 자동으로 표시됩니다. 양방향 추적이 자연스럽게 되는 것이죠.

PR에서 이슈 자동 닫기:

PR 본문이나 커밋 메시지에 아래 키워드를 쓰면, PR이 머지될 때 해당 이슈가 자동으로 닫힙니다:

Closes #31
Fixes #31
Resolves #31

6. GitHub Projects와 통합하기

6.1 Projects란?

GitHub Projects는 이슈와 PR을 칸반 보드, 테이블, 로드맵 뷰로 시각화하는 도구입니다.

6.2 Projects + Issues 연동

Project: "Sprint Manager v2.0"
├── View: Board (상태별)
│   ├── Backlog: #33, #36, #37
│   ├── In Progress: #32
│   └── Done: #31
├── View: Roadmap (타임라인)
│   ├── 3월: #31, #32
│   ├── 4월: #33, #34
│   └── 5월: #35, #36, #37
└── View: Table (전체 목록)
    └── 필터: label:open-core, 정렬: phase

6.3 자동화 워크플로우

Projects에서 설정할 수 있는 빌트인 자동화:

7. 실전: 대규모 프로젝트 이슈 관리 워크플로우

7.1 전체 흐름

1. 라벨 체계 설계
   └── 카테고리별 라벨 생성

2. Epic 이슈 작성
   └── 전체 맥락, 아키텍처 결정, 하위 이슈 체크리스트

3. Phase별 하위 이슈 작성
   └── 각 이슈에 구현 상세, 의존성, 검증 방법

4. Epic 고정 (Pin)
   └── Issues 탭 최상단에 로드맵 고정

5. Projects 보드 연결
   └── 칸반/로드맵 뷰로 시각적 관리

6. 작업 → PR → 이슈 자동 닫기
   └── Closes #31 으로 연결

7.2 라벨 체계 예시

실전에서 효과적이었던 라벨 체계입니다:

# 프로젝트/기능 그룹
gh label create "open-core" --color "6f42c1" --description "Open-Core 전환"

# 단계별 (색상 그라데이션으로 순서 표현)
gh label create "phase:0" --color "bfd4f2"
gh label create "phase:1" --color "a2d5f2"
gh label create "phase:2" --color "7ec8e3"
gh label create "phase:3" --color "5ab0cd"
gh label create "phase:4" --color "3899b8"
gh label create "phase:5" --color "1a82a3"

# 기본 유형 (GitHub 기본 라벨 활용)
# bug, enhancement, documentation 은 이미 존재

# 추가 분류
gh label create "ux" --color "1d76db" --description "UX 개선"
gh label create "security" --color "ee0701" --description "보안 관련"
gh label create "performance" --color "fbca04" --description "성능 개선"

색상 그라데이션 팁: Phase 라벨은 밝은 색 → 어두운 색으로 그라데이션을 주면 Issues 목록에서 진행 순서가 시각적으로 드러납니다.

7.3 의존성 관리 패턴

GitHub Issues 자체에는 "이 이슈가 저 이슈를 블로킹한다"는 공식 기능이 없습니다. 대신 이슈 본문에 의존성을 명시하는 패턴을 사용합니다:

## 의존성
- **선행 (Blocked by)**: #32 (DB 추상화), #33 (에디션 시스템)
- **후행 (Blocks)**: #35 (멀티테넌시), #36 (UI 통합)

이렇게 적으면:

1. 해당 이슈 번호가 자동 링크됨
2. 참조된 이슈에 역참조 표시됨
3. 작업 순서가 문서화됨

더 정교한 의존성 관리가 필요하다면 GitHub Projects의 커스텀 필드를 활용하거나, Sub-Issues의 계층 구조로 순서를 암시할 수 있습니다.

7.4 gh CLI로 이슈 관리하기

터미널에서 바로 이슈를 관리할 수 있습니다:

# 이슈 목록 (라벨 필터)
gh issue list --label "open-core"

# 이슈 상세 보기
gh issue view 38

# 이슈 생성
gh issue create --title "feat: 로그인 기능" \
  --label "enhancement,phase:3" \
  --body "## 배경\n..."

# 이슈 생성 (긴 본문은 heredoc)
gh issue create --title "Phase 1: DB 추상화" \
  --label "open-core,phase:1" \
  --body "$(cat <<'EOF'
## 배경
SQLite와 PostgreSQL 듀얼 지원을 위한 DB 추상화 레이어.

## 구현 상세
...
EOF
)"

# 이슈 닫기
gh issue close 31

# 이슈 고정
gh issue pin 38

# 라벨로 필터 + JSON 출력
gh issue list --label "open-core" --json number,title,labels \
  --jq '.[] | "#\(.number) \(.title)"'

8. 실전 팁 모음

8.1 이슈 작성 체크리스트

이슈를 작성할 때 이 질문들을 확인해보세요:

• [ ] 3개월 후의 나(또는 동료)가 읽어도 바로 이해할 수 있는가?
• [ ] 왜(Why)가 명확한가? 단순히 "무엇을"만 적지 않았는가?
• [ ] 기술적 결정의 근거(대안 비교)가 포함되어 있는가?
• [ ] 구체적인 파일 경로가 포함되어 있는가?
• [ ] 의존성(선행/후행)이 명시되어 있는가?
• [ ] 검증 방법이 체크리스트로 정리되어 있는가?
• [ ] 참고할 보일러플레이트나 문서 링크가 있는가?

8.2 이슈 네이밍 컨벤션

커밋 메시지와 동일한 컨벤션을 쓰면 일관성이 유지됩니다:

feat: 로그인 기능 추가
fix: 세션 만료 시 리다이렉트 오류
refactor: DB 추상화 레이어 분리
docs: API 문서 업데이트
chore: Docker 설정 최적화

Phase 기반 프로젝트라면 Phase 번호를 접두사로:

Phase 0: 오픈소스 릴리스 준비 (AGPL-3.0 + CLA)
Phase 1: DB 추상화 레이어 (SQLite + PostgreSQL)
Phase 3: 인증 시스템 (Better Auth + Organization)

8.3 언제 이슈를 쪼개야 할까?

8.4 닫힌 이슈 활용

닫힌 이슈는 삭제하지 마세요. 프로젝트의 의사결정 기록입니다.

# 과거 결정 검색
gh issue list --state closed --search "인증"
gh issue list --state closed --label "open-core"

"왜 Better Auth를 선택했지?"가 궁금할 때, 해당 이슈를 열면 당시의 비교 분석과 논의가 고스란히 남아있습니다.

9. 정리: GitHub Issues 관리 베스트 프랙티스

10. FAQ

Q: Sub-Issues가 없는 GitHub Enterprise Server를 쓰고 있어요. 어떻게 하나요?
A: 마크다운 체크리스트 + 이슈 번호 참조 패턴을 사용하세요. - [ ] Phase 1: DB 추상화 — #32 형태로 적으면 이슈가 닫힐 때 취소선이 표시됩니다.

Q: 라벨이 너무 많아지면 어떡하나요?
A: 카테고리:값 네이밍 컨벤션을 쓰세요. phase:1, area:backend처럼 하면 카테고리별로 정렬되고, 안 쓰는 라벨은 주기적으로 삭제하세요.

Q: Issue Type과 Label 중 하나만 써야 한다면?
A: Label을 쓰세요. Issue Type은 조직 레벨 기능이라 개인 리포지토리에서는 사용할 수 없습니다. Label은 어디서든 동작합니다.

Q: Epic 이슈는 언제 닫나요?
A: 모든 하위 이슈가 닫힌 후에 닫으세요. Sub-Issues를 사용하면 진행률이 자동 표시되므로, 100% 달성 시 닫으면 됩니다.

Q: 이슈 Pin은 3개 제한인데, 더 많이 고정하고 싶어요.
A: Epic을 하나만 Pin하고, 그 Epic 안에 모든 하위 이슈를 체크리스트로 연결하세요. Epic 하나가 전체 로드맵 역할을 합니다.

11. 참고 자료

• GitHub Issues 공식 기능 페이지
• Sub-Issues 소개 블로그 (GitHub Engineering)
• GitHub Labels 관리 공식 문서
• GitHub Milestones 공식 문서
• GitHub Issue Types 관리 공식 문서
• Pin 이슈 공식 문서
• GitHub Projects 베스트 프랙티스 공식 문서
• Evolving GitHub Issues and Projects (GA 발표)