서론: Github Project 사용 배경

서론: GitHub Project 사용 배경

최근 새로운 프로젝트를 시작하며 팀에서 사용할 프로젝트 관리 도구를 고민하게 됐다. 필요했던 기능은 간단했다. 기획자가 한 곳에서 프로젝트 전체의 이슈를 쉽게 추가하고, 진행 상황을 빠르게 파악할 수 있어야 했다.

처음 고려했던 도구는 Jira와 Confluence였다. 하지만 알아볼수록 이슈와 PR을 연결하려면 티켓 넘버를 일일이 입력해야 하는 등 관리 절차가 복잡했다. 게다가 나를 포함해 팀 내에서 이 도구들에 익숙한 사람이 없었고, 짧은 프로젝트 기간 동안 새로운 도구를 배우면서 사용하는 것은 부담스러웠다. 무턱대고 도입했다가는 오히려 관리 자체가 소홀해질 수도 있을 것 같았다. 그래서 우리 팀 상황에 맞게 더 간단하면서도 효율적인 관리 방법을 찾게 되었다.

이러한 과정에서 GitHub가 기본적으로 제공하는 GitHub Organization과 GitHub Project를 발견하게 되었고, 여러 Repository의 Issue를 한 개의 Project에서 통합적으로 관리할 수 있다는 점이 마음에 들어 이를 실제 프로젝트에 도입하기로 했다.

과정은 다음과 같다.

본론

1. GitHub Organization 만들기

우리 팀은 현재 BE 1명, iOS 1명, Android 1명의 개발 인원으로 구성되어 있다. 당연히 하나의 Repository에서 모든 코드를 관리하는 건 어려웠기 때문에, 팀원이 추천해 준 GitHub Organization을 만들고 각자 사용할 Repo를 따로 만들어 관리하기로 했다.

Github Organization 생성

Organization을 파면 Repository를 내 개인 계정이 아닌 조직 단위에서 관리하게 된다.

이렇게 계정 아래에 조직 계정같이 별도로 생기는 것을 볼 수 있다.

Organization 안에 Repository 생성

생성한 Organization 내부에 Backend, iOS, Android 등 언어별로 각각의 Repository를 만들어 관리했다. 별도로 만든 .github Repository에 대해서는 이후 따로 설명하겠당.

2. GitHub Project 설정하기

GitHub Project에 대해서는 캠프 튜터님들이나 강연 연사님들 등 많은 분들이 추천해주셨던 도구로, 혼자 미리 뚝딱거려 볼 때 그렇게 어렵지 않았고 우리 팀의 상황과 잘 맞았다고 생각해 채택하게 되었다.

Organization 안에 Project 생성

먼저, Organization 내에 Project를 생성했다. Project는 Organization뿐만 아니라 특정 Repository에도 생성할 수 있다.

Board 생성

나는 초기에 Board로 생성을 하고, Roadmap과 Table 탭도 만들어줬다.
기본적인 저런 칸반 UI는 노션으로도 접해봐서 익숙했다.
Progress 관리는 Draft -> Ready -> In Progress -> Done 으로 일단 만들어뒀는데, 자유롭게 작성하면 될 것 같다. 우리도 하다가 중간에 바뀔수도...

Repository에 Project 연결

이제 본격적으로 이슈를 생성하기 전에, 이렇게 만든 프로젝트를 각 Repo에 연결시켜줘야 한다. 이걸 연결해야 Project에서 이슈에 연결할 Repo를 선택할 수 있고, 여기서 만든 issue가 개인 Repo에 연동되어 보여지게 된다.

각 Repository에 들어가서 Project 탭에 가면,
New Project 옆에 위와 같이 Link a Project가 있는 것을 볼 수 있다.
이걸 눌러서 아까 만든 Project를 검색하고, 연결하면 된다.

한 프로젝트 안에서 관리할 Repo를 모두 연결해주면 된다!

Add Item: 이슈 생성

이제 이슈를 생성해보자!

요렇게 저 밑에 Add Item을 클릭하고 이슈 제목을 적으면 사진과 같이 선택창이 올라온다. 나는 Draft 템플릿을 따로 만들어 둬서 그냥 엔터만 쳐도 되도록 했다.

참고로 Add item from repository 하면 여기에 등록되지 않은 레포의 issue를 가져올 수 있는 것 같다.

Create Issue

위 창에서 엔터를 누르면 다음과 같은 창이 뜬다.

아까 연결했던 Repo를 선택할 수도 있고, 템플릿을 선택(템플릿이 없으면 빈칸에 작성)할 수 있다.

이제 여기에 빈 Draft를 작성하면,

요렇게 새로운 드래프트가 생긴다!

이렇게 작성한 issue는 위에서 말했듯이 각 Repo로 들어간다.

3. .github Repository 활용하기

위에서 이슈템플릿을 보여줬는데, 이걸 각 레포마다 설정해줄 수도 있지만 .github repo를 사용해 Organization 안에서 한번에 관리할 수가 있었다. 이 특별한 repo를 사용하면, Issue, PR Template 등 자주 사용하는 공통 설정을 중앙에서 관리도 할 수 있고 Organization의 Readme를 작성할 수도 있다.

.github repo 생성

.github 레포를 생성해보자.
레포 이름을 저렇게 입력하면, 밑에 이스터에그같이 뭐가 뜬다.

Organization의 Public Readme.md를 작성할 수 있는 Repo라고 한다.
이를 위해, 1) .github Repo의 공개 설정이 Public이어야 하고, 2) README.md는 다음과 같은 profile 디렉토리 안에 있어야 한다고 한다.

템플릿 문서 생성

트러블슈팅과 함께 기록

Trouble: ⚠️ GitHub Organization에서 ISSUE_TEMPLATE 적용 안 됨

기존 개별 레포지토리에선 이슈나 PR 템플릿을.github/ISSUE_TEMPLATE/어쩌구저쩌구.md 경로로 저장하는데, 뭔가 얘는 Repo 이름 자체가 .github 니까 바로 최상단에 ISSUE_TEMPLATE/ 디렉토리를 생성해도 될 것 같았다. 이제 여기에 마크다운 파일을 넣고 프로젝트 단에서 이슈를 만들어봤는데 안 먹는 것이다...

GitHub 공식 토론 (#22451)을 참고한 결과, Organization 레벨에서 공통 Issue Template을 적용하려면, 다음과 같은 구조로 템플릿 문서를 생성해야 했다.

✅ 올바른 구조

.github (repo)
└─ .github (directory)
    └─ ISSUE_TEMPLATE
        ├─ bug_report.md
        └─ task.md
        └─ Draft.md

즉, .github Repository 안에 다시 .github 디렉토리를 만들어야 정상 적용이 된다.

+) 참고로 각 Repo 안에 readme든 템플릿이든 개별 설정이 있다면, 그게 우선적으로 적용된다고 한다.

결론

앞으로 프로젝트를 진행하면서 이번에 사용하지 않은 다른 기능들도 추가로 활용해 보고, 우리 팀에 더 적합한 형태로 점점 발전시켜 나갈 예정이다.