Git hook 활용하여 동적 Gitlab MR templates 설정하기

limhi·2024년 5월 8일

GitLab git

Merge Request Template 도입 👀

Git의 Merge Request(MR) 는 변경사항을 제안하고 피드백을 받으며 궁극적으로 코드를 코드베이스에 통합할 수 있도록 해주는 중요한 역할을 합니다.

gitlab 의 MR 페이지

MR을 작성하는 입력란 중 하나인 MR Description 은 변경사항에 대한 단순한 요약 뿐만 아니라, 검토자 및 이해 관계자 간의 의사소통 수단으로 사용됩니다.

또한 잘 작성된 설명은 코드를 효과적으로 검토하는 방법에 대한 지침 을 제공합니다.

따라서 이를 일관성있게 '잘' 작성하고자 Gitlab의 기능 중 하나인 Description Templates를 설정하는 방법에 대해 알아보았습니다.

Description Templates 설정 방법

Gitlab에서 제공하는 모든 템플릿은 마크다운 문서로 작성하여 .gitlab 디렉토리에 저장해야 합니다. 순서는 다음과 같습니다.

repository root 경로에 .gitlab 디렉토리를 생성
.gitlab/issue_templates/ 내부 md 파일은 issue 템플릿으로 활용
.gitlab/merge_request_templates/ 내부 md 파일은 MR 템플릿으로 활용

아래는 임의로 작성한 템플릿 예시입니다.

// .gitlab/merge_request_templates/default.md

## 작업내용
- 기능에서 어떤 부분이 구현되었는지 설명해주세요.

## 추가과제
- 추가적으로 진행되어야 할 과제 혹은 다음 과제를 작성해주세요.

## Jira 링크
- [티켓번호 - 숫자](해당 url)

// .gitlab/merge_request_templates/bug_request.md

## 오류내용
- 오류 내용에 대해서 설명해주세요.
- ex) ~ 했을 시, ~ 상황 발생한 오류

## 해결책
- 구현된 수정 사항이나 솔루션을 설명해주세요.

## Jira 링크
- [티켓번호 - 숫자](해당 url)

위 md 파일을 main 브랜치에 push 후, template를 적용해 issue 또는 MR을 작성할 수 있습니다.

Template 적용 후, 기대효과

템플릿을 적용하였을 때의 기대효과는 다음과 같습니다.

일관성
MR이 일관된 구조를 따르도록 보장하기에 검토자의 검토 프로세스가 단순화됩니다.

시간 절약
사전 정의된 템플릿을 사용하면 변경사항에 대해 무엇을 포함하는 지 파악하는 데 소요되는 시간이 줄어듭니다. 따라서 더욱 빠르게 검토하고 merge 할 수 있습니다.

명확성
템플릿은 변경사항에 대해 명확하고 체계적인 방식으로 필요한 정보를 제공하도록 권장합니다. 이러한 명확성은 검토자가 목적에 대해 이해하는 데 도움이 되며 오해를 최소화합니다.

문서화
잘 정리된 템플릿은 코드 변경에 대한 문서 역할을 할 수 있으며 변경 이면의 의도에 대한 기록을 제공하므로 향후 유지 보수 측면에서 용이합니다.

이처럼 Gitlab에서 MR 템플릿을 단순화하면 검토 프로세스의 효율성과 협업이 크게 향상될 수 있습니다.

그렇게 팀 내의 컨벤션을 정의하여 템플릿을 적용한다면 보다 효율적이고 체계적으로 작업할 수 있을 것이라고 예상하였습니다만...

그렇게 MR Template 를 사용해보니 🧐

하지만 테스트 삼아 MR Template 를 몇 번 작성해보니, 작업한 파일명을 일일이 찾아서 작성해야 하는 번거로움을 느꼈습니다.

이에 대해 Git hook 의 pre-push 를 활용하여 동적으로 MR templates 이 작성되도록 해결하는 방식을 채택 하였습니다.

Git hook 이란?

앞서 Git hook 이란, git 과 관련한 어떤 이벤트가 발생했을 때 특정 스크립트를 실행할 수 있도록 하는 기능을 말합니다.

Git hook 은 크게 클라이언트 훅과 서버 훅으로 나뉘는데 그 구분은 아래와 같습니다.

클라이언트 훅: commit, merge, push 발생 전 클라이언트에서 실행

서버 훅: git repo 로 push 가 발생되었을 때 서버에서 실행

그 중, 동적 Gitlab MR templates 를 설정하기 위해 활용할 pre-push 는 클라이언트 훅에 해당하며 git push 명령 실행 전에 작동하는 스크립트를 의미합니다.

이는 remote 정보를 업데이트 한 후 데이터를 전송하기 전 실행하며, 스크립트 로그에 에러가 있을 시 push 중단이 가능합니다.

Git hook 설정

Git hook 을 실행할 스크립트는 .git/hooks 디렉토리 안에 저장됩니다.

Shell script 로 작성되며 설정하고자 하는 훅을 확장자 없이 파일명으로만 지정하면 적용이 가능합니다.
e.g.) .git/hooks/pre-push

저희 팀의 프론트엔드 측 repo 에는 git hook 에 대한 라이브러리인 Husky 가 도입되어 있었으며, 따라서 해당 라이브러리를 사용하여 pre-push 를 적용하고자 하였습니다.

Husky 란?

git hooks 를 적용하게 해주는 라이브러리
.husky 폴더 내에 스크립트를 저장하면 git hook 을 협업하는 다른 개발자와 공유 가능

왜 husky 를 써야할까?

./git 디렉토리는 기본적으로 git ignore 대상이므로 git hook 을 공유하기 위해서는 별도의 작업이 필요합니다.
따라서 해당 라이브러리를 활용한다면 별도의 디렉터리에 저장하거나 수동으로 공유하는 등의 불필요한 작업을 생략할 수 있습니다.

pre-push 작성

기존에 작성되었던 pre-push 훅의 경우 아래와 같이 단순하게 format 과 lint 명령어를 실행하는 정도로만 활용되었습니다.

pnpm lint
pnpm format

그리고 달성해야 할 조건을 아래와 같이 정리하였습니다.
(팀에서 정의된 git-flow 에 따라 한정되어 있습니다.)

develop 브랜치와 비교하여 달라진 파일명이 template 에 자동으로 작성되도록 한다.
기존에 MR 에 작성되었던 양식을 일반화 하도록 한다.
이전에는 pnpm lint 와 pnpm format 을 실행하였을 시 이에 대해 변경된 파일이 push 에 포함되지 않았으나, git add 명령어와 git commit 명령어를 실행하도록 하여 변경사항을 포함시킨다.

그렇게 최종적으로 작성된 스크립트는 아래와 같습니다.

# 전 처리 과정: 기존에 작성되었던 MR template 을 찾아서 삭제
find .gitlab/merge_request_templates/ -type f -name "merge-into-develop.md" -exec rm {} \;

# 1번 조건: develop 브랜치와 비교하여 변경사항이 있는 파일의 파일명만 가져옴
files=$(git diff develop --name-only)

# 2번 조건: 기존의 양식을 일반화시켜 변경사항 파일명이 포함된 MR template 작성
echo "## 작업내용
// 작성을 용이하게 할 변경내용입니다.
${files}
- merge 할 브랜치의 위치를 확인해주세요.
- 새로 작성된 파일이 어떠한 목적을 가지고 구현되었는지 상세하게 기술해주세요.
### 추가내용
- 추후과제 혹은 Reviewer 들이 집중해서 리뷰 해 주면 좋을 것 같은 점들을 작성해주세요.
" > .gitlab/merge_request_templates/merge-into-develop.md

# lint 와 format 명령어 실행
pnpm lint
pnpm format

# 3번 조건: 위의 변경사항이 포함된 파일 포함하여 커밋 추가
git add .
git commit -m "pre-push hook"