GitHub Foundations #4 Domain 3-1: 협업 — Issue·라벨·마일스톤·템플릿

이번 편부터 두 편에 걸쳐 Domain 3, 협업 기능을 다룹니다. 협업 도메인은 공식 스터디 가이드 기준으로 시험에서 가장 비중이 큰 영역입니다. GitHub를 Git 호스팅을 넘어 협업 플랫폼으로 만든 기능들이 모두 여기에 모여 있고, 문항 수도 그만큼 많이 배정됩니다. 전반부인 이번 글은 Issue를 중심으로 한 작업 추적, 후반부인 다음 글은 Pull Request를 중심으로 한 코드 리뷰를 정리합니다.

Issue — 작업 추적의 기본 단위 #

Issue는 버그 신고, 기능 요청, 할 일을 기록하는 GitHub의 작업 추적 단위입니다. 저장소마다 독립된 Issue 목록이 있고, 번호는 저장소 안에서 1부터 순서대로 붙습니다. 한 가지 알아 둘 점은 Issue와 Pull Request가 번호 체계를 공유한다는 사실입니다. Issue #3 다음에 PR을 열면 그 PR이 #4가 됩니다.

Issue에는 다음 요소를 붙일 수 있습니다.

• Assignees — 담당자입니다. 한 Issue에 여러 명을 지정할 수 있습니다.
• Labels — 분류 태그입니다. 아래에서 따로 다룹니다.
• Milestone — Issue가 속한 목표 묶음입니다. 하나만 지정할 수 있습니다.
• Projects — 프로젝트 보드와의 연결입니다. Domain 5에서 다룹니다.

멘션과 참조 — @와 #의 구분 #

Issue와 PR의 본문, 코멘트에서 쓰는 두 기호는 시험에서 자주 구분을 묻습니다.

• @사용자명 — 멘션입니다. 그 사람에게 알림을 보냅니다. @octocat 확인 부탁드립니다처럼 사람을 부르는 용도입니다. 팀 단위 멘션(@org/team-name)도 가능합니다.
• #번호 — 참조입니다. 같은 저장소의 Issue나 PR로 링크를 만듭니다. #12에서 논의한 내용입니다처럼 문서를 가리키는 용도입니다.

참조는 방향이 기록됩니다. Issue A의 본문에서 #B를 참조하면, B 쪽 타임라인에도 “A에서 이 Issue를 언급했다"는 크로스 레퍼런스가 남습니다. 다른 저장소의 Issue를 가리킬 때는 owner/repo#번호 형식을 쓰고, Issue URL을 본문에 그대로 붙여 넣어도 GitHub가 자동으로 참조 링크로 바꿔 줍니다.

닫는 키워드 — 커밋과 PR로 Issue 닫기 #

Issue를 손으로 닫는 대신, 수정 사항이 머지될 때 자동으로 닫히게 만들 수 있습니다. PR 본문이나 커밋 메시지에 닫는 키워드 + Issue 번호를 적는 방식입니다.

fixes #12
closes #12
resolves #12

세 키워드는 효력이 같고 활용형(fixed, closed, resolved 등)도 인식됩니다. 동작 조건이 시험 포인트입니다. 기본 브랜치(main)에 머지되는 시점에 Issue가 닫힙니다. 다른 브랜치에 머지되는 것만으로는 닫히지 않습니다. 여러 Issue를 한 번에 닫으려면 fixes #12, fixes #34처럼 키워드를 Issue마다 반복해야 합니다.

라벨 — 분류와 필터링 #

라벨은 Issue와 PR을 분류하는 색깔 태그입니다. 새 저장소에는 기본 라벨 셋이 들어 있습니다. bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question, wontfix의 9종입니다. 이 중 good first issue와 help wanted는 오픈소스에서 기여자를 부르는 관례적 라벨로, Domain 7(커뮤니티)과도 연결되는 시험 포인트입니다.

라벨은 저장소 설정에서 자유롭게 추가, 수정할 수 있고, 검색 필터로 활용됩니다.

is:open label:bug                  열려 있는 bug 라벨 Issue
is:issue assignee:@me              내가 담당자인 Issue
is:open no:label                   라벨이 없는 열린 Issue

마일스톤 — 목표 단위의 묶음 #

마일스톤은 릴리스나 스프린트처럼 기한이 있는 목표로 Issue와 PR을 묶는 기능입니다. 마일스톤 페이지에서는 포함된 Issue 중 닫힌 비율이 진행률 막대로 표시되고, 기한(due date)을 지정해 남은 시간을 추적할 수 있습니다. 라벨이 성격에 따른 가로 분류라면, 마일스톤은 일정에 따른 세로 묶음입니다. Issue 하나에 라벨은 여러 개를 붙일 수 있지만 마일스톤은 하나만 지정할 수 있다는 차이도 기억해 둘 지점입니다.

Issue 템플릿과 폼 #

빈 Issue 양식은 신고 품질이 제각각이 되기 쉽습니다. 저장소에 템플릿을 두면 Issue 작성 화면에서 양식을 골라 시작하게 만들 수 있습니다. 템플릿은 .github/ISSUE_TEMPLATE/ 디렉터리에 둡니다.

• 마크다운 템플릿(bug_report.md) — 미리 채워진 본문을 제공하는 단순한 형식입니다.
• Issue 폼(bug_report.yml) — YAML로 정의하는 구조화된 입력 폼입니다. 텍스트 입력, 드롭다운, 체크박스 같은 필드를 강제할 수 있어 필수 정보 누락을 막습니다.

blank_issues_enabled: false
contact_links:
  - name: 사용법 질문
    url: https://github.com/example/repo/discussions
    about: 질문은 Discussions 를 이용해 주세요

config.yml은 템플릿 선택 화면 자체를 제어합니다. blank_issues_enabled: false는 템플릿 없이 빈 Issue를 여는 것을 막고, contact_links는 Issue 대신 안내할 외부 링크를 추가합니다.

알림 — Watch 수준과 관리 #

저장소 우상단의 Watch 버튼으로 알림 수준을 고릅니다.

알림은 웹의 알림함(inbox)과 이메일로 전달되며, 개별 Issue나 PR 단위로도 Subscribe/Unsubscribe를 지정할 수 있습니다. 반복해서 쓰는 코멘트가 있다면 saved replies로 저장해 두고 코멘트 입력창에서 불러 쓸 수 있습니다.

GitHub Flavored Markdown — 협업 화면에서 쓰는 구조 문법 #

GFM 기본 문법과 멘션, 참조는 #2에서 정리했습니다. 협업 도메인에서는 여기에 더해 Issue와 PR 본문을 구조화하는 문법이 출제 포인트가 됩니다.

- [ ] 미완료 태스크        ← 태스크 리스트 (Issue 에서 체크박스로 렌더링)
- [x] 완료된 태스크

| 열1 | 열2 |               ← 표
| --- | --- |

```python                   ← 코드 펜스 (언어명으로 하이라이팅)
print("hello")
```

<details>                   ← 접기/펼치기
<summary>제목</summary>
숨겨진 내용
</details>

태스크 리스트는 단순한 표시가 아니라 Issue 본문에 넣으면 진행률로 집계되고, PR 본문에서는 체크리스트로 활용됩니다. 이 밖에 취소선(~~텍스트~~), 각주, 이모지 표기(:tada:)도 GFM 범위입니다.

마무리 #

이번 글은 협업 도메인의 전반부로 Issue를 중심으로 한 작업 추적 기능을 정리했습니다. 멘션과 참조의 구분, 닫는 키워드의 동작 조건, 템플릿과 폼의 차이, GFM 문법이 이 영역의 핵심입니다.

다음 글인 “GitHub Foundations #5 Domain 3-2: 협업 — Pull Request·코드 리뷰·Discussions"에서는 협업 도메인의 후반부로 Pull Request의 라이프사이클과 코드 리뷰, Issue와 자주 비교되는 Discussions, 그리고 GitHub Pages까지 정리하겠습니다.