이전 장에서는 브랜치에서 작업하고 Pull Request로 main에 합치는 흐름을 배웠습니다. 이제 그 앞단계를 정리할 차례입니다. 바로 "무슨 일을 해야 하는가?"를 기록하고 관리하는 일입니다.
GitHub는 코드만 저장하는 곳이 아닙니다. 해야 할 일, 버그, 개선 아이디어, 회의에서 나온 결정까지 한곳에 모아 관리할 수 있습니다. 이때 사용하는 핵심 기능이 Issues와 Projects입니다.
간단히 말하면, Issue는 작업 카드이고 Project는 작업 보드입니다.
Issue는 할 일을 기록하는 카드다
Issue는 저장소 안에서 관리하는 작업 단위입니다. 새 기능, 버그, 문서 수정, 개선 아이디어처럼 "처리해야 할 일"을 하나씩 카드로 만들어 기록합니다. GitHub 공식 문서에서도 Issues를 아이디어와 작업을 추적하는 도구로 설명합니다.1
예를 들어 다음과 같은 작업은 모두 Issue로 만들 수 있습니다.
로그인 버튼이 동작하지 않음
README에 설치 방법 추가
회원가입 화면 디자인 개선
배포 전에 환경 변수 문서 정리
검색 기능 추가 아이디어 검토
처음에는 Issue를 너무 어렵게 생각하지 않아도 됩니다. 메모장에 할 일을 적는 대신, GitHub에 작업 카드를 만든다고 생각하면 됩니다.
Issue를 만들려면 저장소에서 다음 순서로 이동합니다.
저장소 페이지로 이동
상단의 Issues 탭 클릭
New issue 클릭
제목과 내용을 작성
필요하면 오른쪽 설정 지정
Create 또는 Submit new issue 클릭
만약 Issues 탭이 보이지 않는다면 저장소의 Settings → Features → Issues가 꺼져 있을 수 있습니다. 이 경우 Issues 기능을 켜면 됩니다.
좋은 Issue는 읽는 사람이 바로 이해한다
Issue의 핵심은 "나중에 봐도 무슨 일인지 알 수 있게 쓰는 것"입니다. 제목은 짧고 구체적으로 씁니다. 본문에는 필요한 정보를 마크다운으로 정리합니다.
나쁜 제목의 예는 다음과 같습니다.
수정 필요
에러남
README 작업
좋은 제목은 조금 더 구체적입니다.
README에 설치 방법 추가
Safari에서 로그인 버튼이 클릭되지 않는 문제
회원가입 폼에 이메일 형식 검증 추가
본문은 작업 종류에 따라 다르게 쓰면 됩니다. 버그라면 "문제 상황, 재현 방법, 기대 결과"가 중요합니다. 새 기능이나 문서 작업이라면 "목표, 해야 할 일, 완료 기준"이 중요합니다.
예를 들어 README 설치 방법을 추가하는 Issue는 이렇게 작성할 수 있습니다.
## 작업 내용
README에 프로젝트 설치 방법을 추가합니다.
## 필요한 이유
처음 프로젝트를 받은 사람이 실행 방법을 바로 알 수 있어야 합니다.
## 해야 할 일
- [ ] Node.js 버전 안내
- [ ] 의존성 설치 명령어 추가
- [ ] 로컬 실행 명령어 추가
- [ ] 실행 확인 방법 추가
## 완료 기준
README만 보고 프로젝트를 설치하고 실행할 수 있으면 완료입니다.여기서 - [ ]는 체크리스트입니다. 작업을 진행하면서 완료한 항목을 체크할 수 있습니다. 초보자에게는 체크리스트를 쓰는 습관이 특히 좋습니다. 큰 작업이 작게 쪼개져서 무엇부터 해야 할지 보이기 때문입니다.
담당자, 라벨, 마일스톤으로 의미를 붙인다
Issue를 만들면 오른쪽에 여러 설정이 보입니다. 처음에는 전부 쓰지 않아도 됩니다. 하지만 협업을 시작하면 이 설정들이 매우 중요해집니다.
Assignees: 누가 할 것인가
Assignees는 담당자입니다. 혼자 작업한다면 자기 자신을 지정하면 됩니다. 팀 프로젝트라면 실제로 작업할 사람을 지정합니다.
담당자가 없으면 일이 떠다닙니다. 누군가 하겠지 생각하다가 아무도 하지 않는 일이 생깁니다. 그래서 Issue를 만들 때는 가능하면 담당자를 정하는 것이 좋습니다.
Labels: 어떤 종류의 일인가
Labels는 이슈의 분류입니다. GitHub에는 기본적으로 bug, documentation, enhancement, help wanted 같은 라벨이 제공됩니다. 필요하면 팀에 맞게 새로 만들 수 있습니다.
초보 프로젝트에서는 다음 정도면 충분합니다.
bug: 오류 수정feature: 새 기능docs: 문서 작업refactor: 코드 구조 개선priority: high: 우선순위 높음priority: low: 우선순위 낮음
라벨을 붙이면 나중에 필터링하기 쉽습니다. 예를 들어 "아직 해결되지 않은 버그만 보고 싶다"면 bug 라벨이 붙은 열린 Issue만 확인하면 됩니다.
Milestone: 언제까지, 어떤 목표로 묶을 것인가
Milestone은 여러 Issue를 하나의 목표로 묶는 기능입니다. 보통 버전, 배포 일정, 스프린트 같은 단위에 사용합니다.
예를 들어 다음처럼 만들 수 있습니다.
v1.0 첫 배포5월 문서 정리로그인 기능 완성
v1.0 첫 배포 마일스톤에 10개의 Issue를 넣고 그중 6개를 닫으면, GitHub에서 진행률을 확인할 수 있습니다. 즉, 마일스톤은 "이번 목표가 얼마나 끝났는가?"를 보는 도구입니다.
정리하면 다음과 같습니다.
| 설정 | 의미 | 예시 |
|---|---|---|
| Assignees | 담당자 | me, teammate-a |
| Labels | 작업 종류와 우선순위 | bug, docs, priority: high |
| Milestone | 목표 일정이나 배포 단위 | v1.0, 이번 주 작업 |
이 세 가지를 사용하면 "누가, 어떤 종류의 일을, 언제까지 처리할지"가 훨씬 분명해집니다.
Projects는 작업 흐름을 보여주는 보드다
Issue가 작업 카드라면, Projects는 그 카드를 올려놓는 보드입니다. GitHub Projects에서는 Table, Board, Roadmap 같은 보기 방식을 만들 수 있고, 저장소의 Issue나 Pull Request를 프로젝트에 추가해 관리할 수 있습니다.2
초보자에게 가장 쉬운 방식은 Board 보기입니다. 칸반 보드처럼 카드를 상태별로 나누어 보는 방식입니다.
가장 기본적인 상태 흐름은 다음과 같습니다.
Todo: 해야 할 일
In Progress: 진행 중인 일
Done: 완료된 일
Projects를 만들려면 보통 다음 순서로 진행합니다.
GitHub 상단 또는 저장소의 Projects 탭으로 이동
New project 클릭
템플릿에서 Board 선택
프로젝트 이름 입력
프로젝트 생성
필요하면 컬럼을
Todo,In Progress,Done으로 정리
프로젝트를 만든 뒤에는 Issue를 보드에 연결해야 합니다. 방법은 두 가지가 있습니다.
첫째, Project 화면에서 + Add item을 눌러 기존 Issue를 추가합니다.
둘째, Issue 화면 오른쪽의 Projects 설정에서 연결할 Project를 선택합니다.
Issue가 보드에 올라오면 카드처럼 보입니다. 작업을 시작하면 Todo에서 In Progress로 옮깁니다. 작업이 끝나면 Done으로 옮깁니다. 보드의 카드를 움직이는 것만으로도 팀원들은 현재 진행 상황을 한눈에 볼 수 있습니다.
여러 저장소 작업도 한 프로젝트에서 볼 수 있다
처음에는 하나의 저장소에서만 Issue를 관리해도 충분합니다. 하지만 실무에서는 저장소가 여러 개로 나뉘는 경우가 많습니다.
예를 들어 하나의 서비스가 이렇게 나뉠 수 있습니다.
frontend저장소backend저장소docs저장소
이때 각 저장소의 Issue를 따로 보면 전체 진행 상황을 파악하기 어렵습니다. GitHub Projects를 사용하면 여러 저장소의 Issue를 하나의 프로젝트에 모아 볼 수 있습니다.
예를 들어 v1.0 출시 준비라는 프로젝트를 만들고, 프론트엔드 Issue, 백엔드 Issue, 문서 Issue를 모두 같은 보드에 올릴 수 있습니다. 그러면 팀 전체가 "출시까지 무엇이 남았는지"를 한 화면에서 확인할 수 있습니다.
초보 단계에서는 이 기능을 바로 깊게 쓰지 않아도 됩니다. 다만 Projects는 저장소 하나에만 묶인 단순 보드가 아니라, 여러 저장소의 작업을 모아 관리할 수 있는 공간이라는 점을 기억해 두면 좋습니다.
PR과 Issue를 연결하면 작업 흐름이 완성된다
Issue는 할 일을 기록합니다. 브랜치는 작업 공간입니다. Pull Request는 작업 결과를 검토하고 병합하는 단계입니다.
이 셋을 연결하면 흐름이 깔끔해집니다.
Issue 생성 → 브랜치 생성 → 작업 및 커밋 → PR 생성 → 리뷰 → 병합 → Issue 닫힘GitHub에서는 PR 본문에 특정 키워드와 Issue 번호를 쓰면, PR이 기본 브랜치에 병합될 때 연결된 Issue가 자동으로 닫힙니다. 예를 들어 Closes #3처럼 작성하면 3번 Issue와 연결됩니다.3
자주 쓰는 키워드는 다음과 같습니다.
Closes #이슈번호Fixes #이슈번호Resolves #이슈번호
예를 들어 5번 Issue가 "README에 설치 방법 추가"라면 PR 본문에 이렇게 씁니다.
## 작업 내용
README에 설치 방법을 추가했습니다.
## 관련 이슈
Closes #5이 PR이 main 브랜치에 병합되면 GitHub가 자동으로 5번 Issue를 닫아줍니다. 직접 Issue를 찾아가서 닫을 필요가 없습니다.
단, 단순히 브랜치에 커밋만 했다고 항상 닫히는 것은 아닙니다. 일반적으로 PR이 기본 브랜치에 병합되는 흐름에서 자동 종료가 동작한다고 이해하면 안전합니다.
실전 예시: README에 설치 방법 추가하기
이제 하나의 작업을 처음부터 끝까지 따라가 보겠습니다.
목표는 README에 설치 방법 추가 작업을 Issue로 만들고, Project 보드에서 진행 상황을 옮긴 뒤, PR 병합으로 Issue를 닫는 것입니다.
1단계: Issue 만들기
저장소의 Issues → New issue를 클릭합니다.
제목은 다음처럼 씁니다.
README에 설치 방법 추가본문은 다음처럼 작성합니다.
## 작업 내용
README에 설치 방법을 추가합니다.
## 해야 할 일
- [ ] Node.js 버전 작성
- [ ] npm install 명령어 작성
- [ ] npm run dev 실행 방법 작성
- [ ] 브라우저 접속 주소 작성
## 완료 기준
처음 프로젝트를 받은 사람이 README만 보고 실행할 수 있습니다.오른쪽 설정은 이렇게 지정합니다.
Assignees: 나 자신
Labels:
docsMilestone:
v1.0 첫 배포Projects:
프로젝트 작업 보드
Issue를 생성하면 번호가 붙습니다. 예를 들어 #5라고 가정하겠습니다.
2단계: Project 보드에서 Todo 확인하기
Project 보드로 이동합니다. 방금 만든 Issue 카드가 보이면 Todo에 둡니다.
이 상태는 "해야 할 일로 등록되었지만 아직 시작하지 않음"을 뜻합니다.
3단계: 작업을 시작하며 In Progress로 이동하기
이제 작업을 시작합니다. Project 보드에서 카드를 In Progress로 옮깁니다.
로컬에서는 새 브랜치를 만듭니다.
git switch -c docs/readme-install-guideREADME를 수정한 뒤 커밋합니다.
git add README.md
git commit -m "docs: add installation guide"
git push -u origin docs/readme-install-guide처음 push할 때 -u를 붙여 두면 이후 같은 브랜치에서는 git push만 입력해도 됩니다.
4단계: Pull Request 만들기
GitHub에서 새 PR을 만듭니다. PR 제목은 다음처럼 씁니다.
README 설치 방법 추가PR 본문에는 관련 Issue를 연결합니다.
## 작업 내용
README에 설치 방법을 추가했습니다.
## 확인한 내용
- 의존성 설치 명령어를 작성했습니다.
- 로컬 실행 명령어를 작성했습니다.
- 접속 주소를 작성했습니다.
## 관련 이슈
Closes #5여기서 중요한 부분은 Closes #5입니다. 이 문장 덕분에 PR과 Issue가 연결됩니다.
5단계: 리뷰 후 병합하기
PR 내용을 확인하고 문제가 없으면 main 브랜치에 병합합니다. 병합이 완료되면 5번 Issue는 자동으로 닫힙니다.
Project 보드에서는 해당 카드의 상태를 Done으로 옮깁니다. 설정에 따라 Issue가 닫힐 때 자동으로 Done으로 이동하도록 만들 수도 있지만, 처음에는 직접 옮기면서 흐름을 익히는 편이 좋습니다.
이제 하나의 작업 흐름이 끝났습니다.
Issue #5 생성
→ Project Todo 등록
→ 작업 시작 후 In Progress 이동
→ 브랜치에서 README 수정
→ PR 생성과 Closes #5 작성
→ PR 병합
→ Issue 자동 종료
→ Project Done 이동처음에는 단순하게 시작하자
Issues와 Projects는 기능이 많습니다. 하지만 처음부터 모든 기능을 쓰려고 하면 오히려 복잡해집니다.
초보자라면 다음 규칙만 지켜도 충분합니다.
할 일이 생기면 먼저 Issue로 만든다.
Issue 제목은 짧고 구체적으로 쓴다.
본문에는 체크리스트를 넣는다.
담당자와 라벨을 지정한다.
Project 보드에서
Todo → In Progress → Done으로 옮긴다.PR 본문에
Closes #이슈번호를 적는다.
이 흐름이 익숙해지면 GitHub는 단순한 코드 저장소가 아니라, 팀의 작업 관리 공간이 됩니다. 누가 무엇을 하고 있는지, 어떤 일이 남았는지, 어떤 PR이 어떤 문제를 해결하는지 자연스럽게 연결됩니다.
다음 장에서는 협업 중 자주 만나는 문제인 충돌 해결과 실수 되돌리기를 다룹니다. 작업을 체계적으로 관리하는 것만큼, 실수를 안전하게 복구하는 능력도 중요합니다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.