들어가며

팀 프로젝트를 진행하면서 프론트엔드(화면) 코드와 백엔드(서버) 코드를 GitHub의 서로 다른 레포지토리에 저장하고 있다. 이렇게 관리하니 문제가 생겼다.

버그 하나를 발견했다고 해 보자. 화면도 고치고 서버도 고쳐야 하는 버그라면, 할 일을 적어 두는 이슈가 프론트엔드 레포지토리에 하나, 백엔드 레포지토리에 하나, 따로따로 생긴다. 코드는 각 레포지토리에 있고 브랜치와 PR도 그 레포지토리에서 만들기 때문에, 그 레포지토리에서 할 일은 그 레포지토리의 이슈로 적어 둔다. 두 이슈는 같은 버그를 가리키는데 서로 이어져 있지 않다. 그래서 하나의 작업을 하려면 두 레포지토리를 오가며 각각의 이슈를 찾아야 했다. 이 문제를 풀려면 이슈를 관리하는 방법이 필요했다. 이번 기회에 GitHub Project를 활용한 이슈 관리 방법을 정리해 보려고 한다.

이슈 전용 레포지토리 하나에 메인 이슈를 모으기로 했다

이슈를 관리하는 방법은 여러 가지가 있다. 다만 다른 방법을 무엇으로 놓고 비교했는지는 이 글에 남기지 않았다. 내가 생각한 방법은 이렇다. 이슈만 관리하는 레포지토리를 하나 만들고, 모든 이슈를 그 안에서 시작한다. 프로젝트에서 문제가 생기면 이슈 레포지토리에 이슈를 만들고, 그 이슈 아래에 frontend 레포지토리와 backend 레포지토리의 서브 이슈를 만들어 관리한다. GitHub의 서브 이슈는 다른 레포지토리에 있는 이슈도 부모 이슈 아래에 달 수 있어서 이 구조가 된다.

이제부터 이슈를 추적하는(트래커 역할) 레포지토리, 그림에서 「이슈 트래킹 레포지토리」라고 적은 것은 I 레포지토리, frontend는 F 레포지토리, backend는 B 레포지토리라고 하겠다. 그리고 I에 만든 부모 이슈를 메인 이슈라고 부른다.

구조도를 그려 보면 이렇게 된다.

graph TD A[이슈 트래킹 레포지토리] --> B[프론트엔드 레포지토리] A[이슈 트래킹 레포지토리] --> C[백엔드 레포지토리]

화살표는 「I의 메인 이슈 아래에 F와 B의 서브 이슈가 달린다」는 뜻이다. 서브 이슈는 여전히 F와 B에 따로 있다. 하지만 메인 이슈 화면에 그 서브 이슈들이 매달려 있으니, 버그 하나에 걸린 일을 찾으려고 두 레포지토리를 뒤질 필요 없이 I의 메인 이슈 하나에서 시작하면 된다. 그래서 모든 이슈를 한 곳에서 관리할 수 있다.

I 레포지토리는 GitHub Project가 아니라 평범한 레포지토리다. 제목에는 GitHub Project를 활용한다고 적었지만, 이 글에서 실제로 정한 것은 이 레포지토리 구조까지다. GitHub Project 화면(보드)에 이슈를 어떻게 모아 볼지는 이 글에서 다루지 않았다.

이슈 하나는 생성부터 메인 이슈 완료까지 열 단계를 거친다

아래는 시퀀스 다이어그램이다. 맨 위에 늘어선 다섯 칸이 참여자이고, 화살표는 위에서 아래 순서로 일어난다. 「작업 발생」은 버그나 할 일을 발견한 쪽이다. 「작업 브랜치」는 실제로 코드를 고치는 갈래다. 그림에는 칸 하나로 그렸지만 브랜치는 F와 B에 하나씩 따로 생긴다. 두 레포지토리가 브랜치 하나를 같이 쓰는 것이 아니다.

sequenceDiagram participant 작업 발생 participant 이슈 트래킹 participant 프론트엔드 participant 백엔드 participant 작업 브랜치 작업 발생 ->> 이슈 트래킹 : 1. 이슈 생성 이슈 트래킹 ->> 프론트엔드 : 2. 서브 이슈 생성 이슈 트래킹 ->> 백엔드 : 3. 서브 이슈 생성 프론트엔드 ->> 작업 브랜치 : 4. 브랜치 생성 및 작업 진행 백엔드 ->> 작업 브랜치 : 5. 브랜치 생성 및 작업 진행 작업 브랜치 ->> 프론트엔드 : 6. PR 생성 및 머지 작업 브랜치 ->> 백엔드 : 7. PR 생성 및 머지 프론트엔드 ->> 이슈 트래킹 : 8. 서브 이슈 완료 백엔드 ->> 이슈 트래킹 : 9. 서브 이슈 완료 이슈 트래킹 ->> 작업 발생 : 10. 메인 이슈 완료

4~5번은 레포지토리에서 작업 브랜치로 갈라져 나가는 화살표이고, 6~7번은 작업 브랜치에서 고친 것을 다시 레포지토리로 합쳐 넣는 화살표다. 8~9번은 F와 B에 있는 서브 이슈를 닫는 일이다. 화살표가 I로 가는 것은 그 서브 이슈들이 I의 메인 이슈 아래에 매달려 있어서, 닫았다는 결과가 메인 이슈 쪽에 모인다는 뜻으로 읽는다. 10번은 메인 이슈를 닫아 처음 일을 꺼낸 쪽에 끝났다고 돌려주는 화살표다. 아래 목록의 번호는 다이어그램 번호와 같다.

  1. I 레포지토리에 메인 이슈를 만들고, 무엇이 문제인지 내용을 상세하게 적는다. 무엇까지 적어야 상세한지는 이 글에서 정하지 않았다.
  2. I의 메인 이슈 아래에 F 레포지토리 서브 이슈를 단다. 메인 이슈 본문 아래에 「Create sub-issue」 버튼이 있고, 옆의 화살표를 누르면 「Add existing issue」가 나온다. 「Add existing issue」에서는 레포지토리를 바꿔 다른 레포지토리의 이슈를 고를 수 있다. 「Create sub-issue」로 새로 만들 때 레포지토리를 고를 수 있는지는 확인하지 않았다.
  3. 같은 방법으로 B 레포지토리 서브 이슈를 만든다.
  4. F 레포지토리에서 이슈 번호로 브랜치를 만들고 작업한다. 이슈는 만들 때마다 번호를 하나씩 받는다. 그 번호를 브랜치에 어떻게 담을지(이름 모양)와, 메인 이슈와 서브 이슈 중 어느 쪽 번호를 쓸지는 이 글에 적어 두지 않았다.
  5. B 레포지토리에서도 같은 방식으로 브랜치를 만들고 작업한다.
  6. F 레포지토리에서 PR을 만들고 머지한다. 머지 전에 누가 리뷰하는지는 이 글에서 정하지 않았다.
  7. B 레포지토리에서 PR을 만들고 머지한다.
  8. F 레포지토리의 서브 이슈를 완료 처리(닫기)한다.
  9. B 레포지토리의 서브 이슈를 완료 처리한다. Closes #N 같은 규칙으로 서브 이슈가 저절로 닫히게 할지, 사람이 닫기 버튼을 누를지는 이 글에서 정하지 않았다.
  10. 서브 이슈가 모두 닫히면 I 레포지토리의 메인 이슈를 완료 처리한다.

앞으로의 계획

프로젝트에서 이슈를 관리하는 방법을 정리해 보았다. 정리한 방법은 완벽한 방법이 아니라서 나중에 바뀔 수 있다. 팀원들과 함께 경험해 보면서 좋은 방법을 찾아봐야겠다.

자신만의 철학을 만들어가는 중입니다.
최상단으로 이동했습니다!
확대 이미지

댓글남기기

다른 포스트

[Concept] 발전소에서 우리 집 220V까지: 자석을 돌려 교류를 만들고 변압기로 전압을 바꾼다

파워 페이지는 「벽 콘센트에서 220V 교류가 들어온다」에서 시작한다. 그 220V가 왜 교류인지, 왜 220V인지는 직류와 교류에서 팠다. 그 글은 「발전기는 돌면서 교류를 만든다」와 「변압기는 감은 수의 비율만큼 전압을 바꾼다」까지만 보고 끝났다. 그 글의 「아직 안 본 것」에...

그래프에서 보기 update 2026-10-23 12:00 - · -