이슈 (Issue)

이슈(Issue)는 소프트웨어 개발에서 해결할 문제나 제안, 작업의 내용과 진행 상황을 기록하고 추적하는 항목입니다. 제목과 본문에 작업을 설명하고, 댓글로 논의하며 담당자나 분류 정보를 붙여 관리합니다. 오류 신고뿐 아니라 새 기능 요청과 문서 개선에도 사용합니다. 개발 도구에서 말하는 이슈는 팀이 논의할 작업을 남기는 기록 단위를 뜻합니다.

작업 내용과 논의를 모으는 기록

GitHub의 이슈 소개는 저장소에서 일을 계획하고 논의하며 추적하는 수단으로 이슈를 설명합니다. 제목은 다룰 작업을 식별하고 본문은 문제의 내용이나 요청을 담습니다. 뒤이어 남긴 댓글에는 추가 정보와 검토 의견이 모입니다. 팀원이 다른 시점에 참여하더라도 처음 제기한 내용과 이후 논의가 같은 항목에 남습니다.

담당자는 누가 작업하는지 나타내고, 라벨과 이슈 유형은 성격에 따라 항목을 분류하는 데 씁니다. 마일스톤은 관련 작업을 묶어 관리할 때 사용합니다. 제목에 모든 관리 정보를 넣는 대신 이런 정보를 별도로 붙이면 필요한 조건으로 작업을 찾기 쉬워집니다. GitHub Projects는 이슈의 메타데이터를 활용해 작업을 여러 보기와 필터로 표시합니다. 이슈 하나를 두고 내용을 논의하면서 작업 계획에도 반영할 수 있습니다.

일의 규모가 크면 하나의 이슈 아래에 하위 이슈를 두어 나눕니다. 로그인 화면 개선에서 입력 오류 표시와 접근성 수정을 나누면 각각의 진행 상황을 추적하면서 상위 작업과의 관계를 남길 수 있습니다. GitHub는 하위 이슈의 계층과 별도로, 어떤 이슈가 다른 작업의 진행을 막는지 나타내는 의존 관계도 제공합니다. 상위 작업에 속한다는 관계와 먼저 끝나야 한다는 관계는 서로 다릅니다.

버그 보고와 코드 변경 요청의 구분

버그는 프로그램의 결함을 가리키며, 이슈는 그 결함을 포함한 여러 종류의 작업을 기록하는 형식입니다. GitHub의 이슈 생성 문서는 버그와 개선 사항, 기타 요청을 추적하는 데 이슈를 쓴다고 설명합니다. 열린 이슈의 수만으로 프로그램의 오류 수를 셀 수는 없습니다. 같은 목록에 기능 제안과 문서 수정 요청도 들어가기 때문입니다.

저장 버튼을 눌렀는데 변경 내용이 남지 않는 문제를 이슈로 적을 때, 발생 조건과 실제 결과를 본문에 남기면 담당자가 무엇을 조사할지 구체화됩니다. 새 기능 요청이라면 필요한 동작과 적용 범위를 적습니다. 앞의 이슈는 원인을 찾아야 할 결함을 설명하고, 뒤의 이슈는 구현 여부를 논의할 요구를 설명합니다. 두 경우 모두 작업을 정의하지만, 생성됐다는 사실만으로 원인이 확인되거나 구현이 확정되는 것은 아닙니다.

풀 리퀘스트(PR)는 코드 변경 내용을 검토하고 병합하도록 제안하는 단위입니다. 이슈가 해결할 일을 설명한다면 PR은 그 일을 위해 준비한 변경 내용을 연결합니다. GitHub의 이슈와 PR 연결 문서에 따르면 둘을 연결하면 협업자가 해당 이슈의 수정 작업이 진행 중임을 확인할 수 있습니다. 이슈에 해결 방안을 적는 것과 변경된 코드가 저장소에 반영되는 것은 별개의 단계입니다.

생성 권한과 완료 처리의 조건

2026년 10월 11일 수집한 GitHub의 이슈 생성 안내는 이슈 기능이 켜진 저장소에서 읽기 권한이 있는 사람이 이슈를 만들 수 있다고 설명합니다. 저장소 관리자는 이슈 기능을 끌 수 있습니다. 또한 이슈를 만들 수 있는 권한과 라벨을 붙이거나 담당자를 지정하는 관리 권한은 구분됩니다. 같은 저장소를 보더라도 역할에 따라 사용할 수 있는 관리 기능이 달라집니다.

PR에 종료 키워드를 넣으면 조건에 따라 연결된 이슈가 자동으로 닫힙니다. GitHub의 연결 규칙은 같은 저장소의 이슈를 가리킬 때 Closes #10 같은 구문을 사용합니다. PR이 저장소의 기본 브랜치를 대상으로 하고 그 브랜치에 병합될 때 연결된 이슈가 닫힙니다. 다른 브랜치를 대상으로 한 PR 설명에서는 종료 키워드가 무시되며, 그 PR을 병합해도 이슈에 영향을 주지 않습니다.

자동 종료는 작업 추적 상태를 바꾸는 규칙입니다. 병합된 변경이 실제 배포됐는지, 처음 신고한 환경에서도 문제가 해결됐는지는 별도의 실행 결과로 확인합니다. 담당자가 재현 조건과 검증 결과를 이슈에 남기면 닫힌 이유를 이후에도 따라갈 수 있습니다. AI 에이전트에게 이슈를 맡기는 경우에도 요구 내용, 관련 코드, 완료 조건이 구체적으로 적혀 있으면 작업 범위와 결과를 대조하기 쉬워집니다.