이슈(Issue)가 뭐야?: 깃허브 이슈로 작업 관리하는 법
깃허브의 어떤 프로젝트에 들어가 보면 항상 보이는 메뉴가 ‘Issues’다. 그 안에 그 프로젝트가 지금 무엇을 고민하고 있는지가 다 들어 있다.
이슈 한 줄 정의
**이슈(Issue)**는 깃허브 같은 협업 플랫폼에서 “해야 할 일·고쳐야 할 버그·논의할 주제”를 카드 한 장에 적어두는 단위다.
풀어 말하면, 프로젝트의 작업·문제·아이디어를 한 곳에 모으는 게시판이다. 한 이슈는 보통 한 가지 주제만 담는다. “로그인 화면이 모바일에서 깨진다”, “다크 모드 추가하면 좋겠다”, “결제 모듈 리팩토링 필요” 같은 식이다.
이슈가 모이면 그게 그 프로젝트의 우선순위 목록이 된다. 누가 어떤 일을 맡는지, 언제 끝나는지를 이슈 단위로 추적한다.
중학생도 이해하는 비유
이슈를 가장 쉽게 설명하는 비유는 포스트잇 게시판이다.
회의실 벽에 색깔별로 포스트잇이 붙어 있다고 상상해 보자. 노란 포스트잇은 버그, 파란 건 새 기능 제안, 빨간 건 긴급. 각 포스트잇에는 짧은 제목과 함께 누가 맡고 있는지, 진행 중인지 끝났는지가 적혀 있다.
이슈가 정확히 이 포스트잇 한 장이다. 라벨로 색을 표시하고, 담당자(Assignee)로 누가 맡는지를 정하고, 댓글로 의견을 주고받는다. 다 끝나면 카드를 떼어내듯 이슈를 닫는다.
이 방식이 좋은 이유는 단순하다. 누구든 게시판만 보면 “지금 뭐가 진행 중이고, 무엇이 막혀 있고, 다음에 뭘 할지”가 한눈에 보인다. 비공개 회의록보다 훨씬 투명하다.
실제 사용 예시
이슈는 보통 이런 식으로 활용된다.
예시 1: 버그 신고
사용자가 “결제 금액이 잘못 표시된다”는 버그를 발견하면, 깃허브 Issues에 버그: 결제 화면 금액이 0 두 자리 더 표시됨 같은 제목으로 새 이슈를 만든다. 본문에는 재현 단계와 화면 캡처를 함께 올린다. 개발자는 이 이슈를 읽고 PR로 수정 작업을 시작한다.
예시 2: 새 기능 제안 “다크 모드를 추가해 달라”는 제안을 이슈로 올리면 다른 사용자도 댓글로 의견을 남긴다. “+1”, “야간에 자주 쓰는 사람으로서 동의”, “iOS 시스템 설정 따라가게 해주세요” 같은 댓글이 모이면, 그 기능의 우선순위가 자연스럽게 정해진다.
예시 3: AI 도구 연동 GitHub Copilot, Claude Code 같은 도구가 이슈 내용을 읽고 자동으로 관련 파일을 찾아 수정 PR을 만들어 주는 기능이 늘고 있다. 사람은 이슈만 잘 적어두면, 코드 변경 제안까지는 AI가 끌고 가준다.
비슷한 용어와 차이
헷갈리기 쉬운 깃허브 개념을 정리했다.
| 용어 | 뜻 | 이슈와의 차이 |
|---|---|---|
| PR(Pull Request) | 코드 변경을 합쳐 달라는 제출 단위 | 이슈는 “할 일”이고, PR은 “이미 한 결과” |
| 마일스톤(Milestone) | 여러 이슈를 묶어 마감일을 정한 단위 | 이슈의 상위 그룹 |
| 라벨(Label) | 이슈·PR을 분류하는 색 태그 | 이슈 자체는 아니고, 이슈에 붙이는 표시 |
| 프로젝트 보드 | 칸반 형태의 진행 상황 보드 | 여러 이슈를 시각적으로 정리 |
| 디스커션(Discussion) | 자유로운 논의용 공간 | 이슈보다 가벼운 토론에 적합 |
따라서 “이슈 = 버그”가 아니다. 이슈는 버그·기능·질문·논의를 모두 담는 일반 단위다.
언제 이슈를 마주치나
이슈라는 단어는 보통 이런 상황에서 등장한다.
- 오픈소스 사용 중 버그 발견: 깃허브 저장소의 Issues 탭에 신고
- AI 코딩 도구 워크플로: “이슈를 만들면 AI가 자동으로 관련 코드를 찾아 PR 생성”
- 회사 협업 도구 비교: “Jira와 GitHub Issues 중 무엇을 쓸까” 같은 비교 글
- 오픈소스 기여 시작: “good first issue” 라벨이 붙은 항목으로 첫 기여 시작
평소 깃허브를 쓰지 않더라도, AI 코딩 도구나 오픈소스 도구를 진지하게 쓰기 시작하면 이슈가 자주 등장한다.
관련 용어
이슈를 이해했다면 함께 알아두면 흐름이 연결되는 용어들이다.
- 레포지토리(Repository): 코드와 이슈, 위키 등이 모두 담기는 프로젝트의 저장 공간.
- PR(Pull Request): 이슈에 적힌 일을 실제 코드 변경으로 끝낸 결과물 제출 단위.
- 커밋(Commit): PR을 구성하는 변경 단위. 한 PR 안에 여러 커밋이 들어간다. 커밋(Commit)이 뭐야?: 코드 변경을 기록하는 방식 정리 참고.
- AI 에이전트: 이슈 내용을 읽고 PR까지 자동으로 만들어 주는 흐름이 등장하고 있다.
이슈는 “프로젝트의 할 일·버그·논의를 한 카드에 적어두는 단위”다. 포스트잇 게시판처럼, 어떤 프로젝트든 그 Issues 탭만 보면 지금의 우선순위가 한눈에 들어온다. AI 코딩 도구가 이슈를 자동으로 처리해 주는 시대가 열리면서, 이슈를 잘 적는 능력 자체가 협업의 기본기가 되고 있다.
출처
- GitHub Docs, About issues, https://docs.github.com/issues/
- Atlassian, Issue tracking 기본 가이드, https://www.atlassian.com/
- Anthropic, Claude Code 기능 안내, https://docs.anthropic.com/
