Issue: 작업과 문제를 추적하는 협업의 단위
이슈(Issue)는 버그, 기능 요청, 작업 항목 같은 할 일을 하나의 단위로 기록하고 논의하는 GitHub·GitLab 등 호스팅 서비스의 기능이다. Git 자체의 기능이 아니라 Git 저장소 호스팅 플랫폼이 제공하는 추적 도구다. 이슈 번호를 커밋과 PR에 연결하면 코드 변경의 이유를 추적할 수 있다.
By 송민성
1. 개념
이슈(Issue)는 저장소(repository) 단위로 만드는 작업 추적 항목이다. 버그 보고, 기능 제안, 질문, 리팩터링 할 일 등을 하나의 이슈로 기록한다. 각 이슈에는 저장소 안에서 고유한 번호(#12)가 붙고, 제목·본문·댓글·라벨(label)·담당자(assignee)·마일스톤(milestone)·상태(open/closed)를 가진다.
이슈는 Git의 기능이 아니다. Git은 커밋, 브랜치, 병합 같은 버전 관리만 담당하며, 이슈는 GitHub, GitLab, Bitbucket 같은 호스팅 서비스가 Git 위에 얹어 제공하는 기능이다. 따라서 .git 디렉터리를 복제(clone)해도 이슈는 따라오지 않는다.
2. 왜 사용하는가
- 기록의 중앙화: 메신저나 구두로 오가는 요청을 한곳에 남겨 유실을 막는다.
- 논의와 코드의 연결: 왜 이 변경이 필요했는지를 커밋·PR(Pull Request)에서 이슈로 거슬러 올라가 확인할 수 있다.
- 역할 분담: 담당자와 라벨로 누가 무엇을 하는지, 어떤 종류의 작업인지 구분한다.
- 진행 관리: 열림/닫힘 상태와 마일스톤으로 릴리스 범위를 관리한다.
3. 동작 원리
이슈의 일반적인 생명주기는 다음과 같다.
- 생성: 문제나 요청을 제목과 본문으로 작성한다. 재현 방법, 기대 동작, 실제 동작을 적으면 좋다.
- 분류(triage): 라벨(
bug,enhancement등), 담당자, 마일스톤을 지정한다. - 작업: 이슈 번호를 딴 브랜치를 만들고 커밋한다. 예:
fix/12-login-error - 연결: PR 본문이나 커밋 메시지에 이슈 번호를 적는다.
- 종료: PR이 기본 브랜치(default branch)에 병합되면, 닫기 키워드가 있는 이슈는 자동으로 닫힌다.
닫기 키워드는 close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved이며, Fixes #12처럼 쓴다. 단순 참조는 #12만 적으면 되고, 이 경우 이슈는 자동으로 닫히지 않고 타임라인에 링크만 남는다. 자동 종료는 PR이 기본 브랜치로 병합될 때 동작한다.
4. 코드 예제
GitHub CLI(gh)로 이슈를 만들고 커밋과 연결하는 흐름이다. gh auth login으로 인증이 되어 있어야 한다.
# 1. 이슈 생성
gh issue create \
--title "로그인 시 500 에러 발생" \
--body "잘못된 비밀번호 입력 시 500이 반환됩니다. 기대 동작: 401" \
--label bug
# 2. 이슈 목록 확인
gh issue list --state open
# 3. 이슈 번호가 12라고 가정하고 브랜치 생성
git switch -c fix/12-login-error
# 4. 수정 후 커밋 (참조만 남김)
git commit -am "fix: 잘못된 비밀번호에 401 반환 (#12)"
# 5. PR 생성 - 본문에 닫기 키워드 사용
git push -u origin fix/12-login-error
gh pr create --title "로그인 에러 수정" --body "Fixes #12"이슈 템플릿은 저장소의 .github/ISSUE_TEMPLATE/ 디렉터리에 마크다운 파일로 두면 된다.
mkdir -p .github/ISSUE_TEMPLATE
cat > .github/ISSUE_TEMPLATE/bug_report.md << 'EOF'