Git hooks로 코드 품질 자동 관리하기

개발 프로젝트에서 코드 품질을 유지하는 것은 매우 중요합니다. 일관된 코딩 스타일, 버그 없는 코드, 그리고 테스트 커버리지 등은 프로젝트의 장기적인 성공과 개발 팀의 생산성에 직결됩니다. 하지만 바쁜 개발 일정 속에서 이러한 품질 관리를 수동으로 진행하는 것은 많은 시간과 노력을 필요로 하며, 휴먼 에러의 가능성도 높습니다.

이러한 문제를 해결하고 개발 프로세스에 코드 품질 관리를 자동화하기 위한 강력한 도구가 바로 Git hooks입니다. Git hooks는 특정 Git 이벤트(커밋, 푸시 등)가 발생할 때 자동으로 실행되는 스크립트로, 개발자가 미처 놓칠 수 있는 부분들을 사전에 검사하고 수정할 수 있도록 도와줍니다. 이번 튜토리얼에서는 Git hooks의 개념부터 실제 프로젝트에 적용하는 방법까지 자세히 알아보겠습니다.

Image by luntan6644 on Pixabay

Git Hooks란 무엇인가요?

Git hooks는 Git 레포지토리에서 특정 이벤트가 발생할 때 자동으로 실행되는 사용자 정의 스크립트입니다. 이 스크립트들은 `.git/hooks` 디렉토리에 위치하며, 파일 이름이 곧 hook의 종류를 나타냅니다. 예를 들어, `pre-commit`이라는 이름의 스크립트는 커밋이 생성되기 전에 실행됩니다. Git hooks는 셸 스크립트, 파이썬, 루비 등 실행 가능한 모든 스크립트 언어로 작성할 수 있습니다.

Git hooks는 크게 두 가지 유형으로 나눌 수 있습니다.

• 클라이언트 측(Client-side) hooks: 로컬 개발자의 컴퓨터에서 실행됩니다. 커밋, 머지 등 로컬 저장소에서 발생하는 이벤트에 반응합니다. 예를 들어, `pre-commit`은 커밋 메시지를 작성하기 전에, `pre-push`는 원격 저장소로 푸시하기 전에 실행됩니다.
• 서버 측(Server-side) hooks: Git 서버에서 실행됩니다. 푸시된 커밋을 수신할 때와 같이 원격 저장소에서 발생하는 이벤트에 반응합니다. 팀 전체의 코드 품질을 강제하거나 특정 브랜치에 대한 접근을 제어하는 데 사용될 수 있습니다.

각 유형의 Git hooks는 프로젝트의 어느 단계에서 품질 관리를 수행할지에 따라 중요한 역할을 합니다. 다음 표에서 클라이언트 측과 서버 측 hooks의 주요 차이점을 비교해 보겠습니다.

구분	클라이언트 측 Hooks	서버 측 Hooks
실행 위치	개발자 로컬 워크스테이션	Git 서버
주요 목적	개인 개발 워크플로우 지원, 로컬에서 빠른 피드백 제공, 커밋 전 코드 품질 검사 (린팅, 포맷팅, 유닛 테스트)	팀 전체의 코드 품질 강제, 보안 정책 적용, 특정 브랜치 보호, CI/CD 트리거
적용 범위	해당 로컬 레포지토리에만 적용	해당 서버를 사용하는 모든 개발자에게 적용
우회 가능성	`--no-verify` 옵션으로 우회 가능	우회 불가 (서버 정책에 따라 강제됨)
관리 방식	각 개발자가 직접 설정하거나, Husky와 같은 도구로 공유	서버 관리자가 설정 및 유지보수

클라이언트 측 Git Hooks 활용: Pre-commit으로 코드 품질 자동화하기

가장 많이 사용되는 클라이언트 측 hook 중 하나는 `pre-commit`입니다. 이 hook은 `git commit` 명령이 실행되고 커밋 메시지를 작성하기 직전에 실행됩니다. `pre-commit` hook을 활용하면 커밋이 원격 저장소에 푸시되기 전에 잠재적인 문제들을 미리 파악하고 수정할 수 있습니다.

주요 활용 사례:

• 코드 린팅(Linting): ESLint, TSLint 등으로 코딩 스타일 및 잠재적 버그 검사
• 코드 포맷팅(Formatting): Prettier 등으로 코드 스타일 자동 정렬
• 간단한 유닛 테스트: 커밋할 변경사항과 관련된 유닛 테스트 실행
• 보안 검사: 민감한 정보(비밀번호, API 키 등)가 커밋되는 것을 방지

Husky와 Lint-staged를 이용한 Pre-commit 설정 (JavaScript/TypeScript 프로젝트 예시)

`.git/hooks` 디렉토리에 직접 스크립트를 작성하는 것도 가능하지만, 팀 프로젝트에서는 모든 개발자가 동일한 hook을 사용하도록 관리하기 어렵습니다. 이럴 때 Husky와 lint-staged 같은 도구를 사용하면 Git hooks를 효율적으로 관리하고 공유할 수 있습니다.

Husky는 Git hooks를 `package.json`에 정의하여 쉽게 관리하고, 모든 팀원이 동일한 hooks를 사용할 수 있도록 해주는 도구입니다. lint-staged는 Git의 "staged" 상태에 있는 파일(커밋될 변경사항)에 대해서만 린터나 포매터 등을 실행하도록 도와줍니다. 이는 불필요한 파일까지 검사하는 것을 방지하여 hook 실행 시간을 단축시킵니다.

설정 단계:

1. Husky와 lint-staged 설치:

npm install --save-dev husky lint-staged
# 또는
yarn add --dev husky lint-staged

1. Husky 초기화 및 pre-commit hook 추가:

npx husky init
npx husky add .husky/pre-commit "npx lint-staged"

위 명령은 `.husky` 디렉토리를 생성하고, `pre-commit` 파일을 추가합니다. 이 파일은 `npx lint-staged` 명령을 실행하도록 설정됩니다.

1. `package.json`에 `lint-staged` 설정 추가:

이제 어떤 파일에 대해 어떤 명령을 실행할지 `package.json`에 정의합니다. 예를 들어, `.js`, `.ts`, `.jsx`, `.tsx` 파일에 대해 ESLint와 Prettier를 실행하도록 설정할 수 있습니다.

// package.json
{
  "name": "my-project",
  "version": "1.0.0",
  // ...
  "devDependencies": {
    "husky": "^8.0.0",
    "lint-staged": "^13.0.0",
    "eslint": "^8.0.0",
    "prettier": "^2.0.0"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "git add"
    ],
    "*.{json,css,md}": [
      "prettier --write",
      "git add"
    ]
  },
  "scripts": {
    "prepare": "husky install"
  }
}

위 설정은 다음과 같이 작동합니다:

• `.js`, `.jsx`, `.ts`, `.tsx` 파일에 대해 `eslint --fix` (자동 수정 가능한 오류 수정) 및 `prettier --write` (자동 포맷팅)를 실행합니다.
• `eslint --fix`나 `prettier --write`로 인해 파일이 수정되면, 수정된 파일을 다시 Git staging area에 추가하기 위해 `git add` 명령을 실행합니다.
• `prepare` 스크립트는 `npm install` 후에 `husky install`을 자동으로 실행하여 `.husky` 디렉토리를 설정합니다.

이제 커밋을 시도할 때마다 `lint-staged`가 `pre-commit` hook을 통해 자동으로 실행되어, staged된 파일에 대한 린팅과 포맷팅을 수행합니다. 만약 린팅 규칙을 위반하거나 포맷팅이 제대로 되지 않은 부분이 있다면, 커밋이 실패하고 개발자에게 피드백을 제공합니다.

Image by AlLes on Pixabay

서버 측 Git Hooks 활용: Pre-receive로 엄격한 품질 관리 구축

서버 측 Git hooks는 클라이언트 측 hooks와 달리 개발자가 쉽게 우회할 수 없다는 강력한 장점이 있습니다. 주로 원격 Git 저장소(GitHub, GitLab, Bitbucket 등) 서버에 직접 스크립트를 배포하여 사용됩니다. `pre-receive` hook은 원격 저장소에 푸시 요청이 들어왔을 때, 실제 커밋이 저장소에 반영되기 전에 실행되는 가장 대표적인 서버 측 hook입니다.

주요 활용 사례:

• 브랜치 보호 및 네이밍 규칙 강제: `main` 브랜치에 직접 푸시하는 것을 막거나, 특정 브랜치(예: `feature/`, `bugfix/`)만 허용하도록 강제합니다.
• CI/CD 파이프라인 연동: 푸시된 코드가 모든 테스트를 통과했는지 확인하고, 실패하면 푸시를 거부하여 결함 있는 코드가 머지되는 것을 방지합니다.
• 커밋 메시지 규칙 강제: 특정 형식(예: Jira 티켓 번호 포함)을 따르지 않는 커밋 메시지를 거부합니다.
• 액세스 제어: 특정 사용자나 그룹만 특정 브랜치에 푸시할 수 있도록 제한합니다.

서버 측 hooks는 직접 설정하기보다는 GitHub Actions, GitLab CI/CD, Bitbucket Pipelines와 같은 CI/CD(Continuous Integration/Continuous Deployment) 서비스를 통해 간접적으로 활용되는 경우가 많습니다. 이러한 서비스들은 Git 이벤트를 감지하여 자동으로 빌드, 테스트, 배포 등의 작업을 수행하며, 이는 사실상 서버 측 hook의 확장된 형태라고 볼 수 있습니다.

예를 들어, GitLab CI/CD에서는 `.gitlab-ci.yml` 파일에 정의된 파이프라인이 `pre-receive` hook처럼 작동하여, 푸시된 코드가 특정 브랜치에 머지되기 전에 모든 테스트를 통과하도록 강제할 수 있습니다. 만약 파이프라인이 실패하면, 해당 푸시가 머지되지 않거나, 머지 요청이 보류됩니다.

GitLab CI/CD 예시: `main` 브랜치에 푸시되기 전 테스트 실행

# .gitlab-ci.yml
stages:
  - test
  - deploy

run_tests:
  stage: test
  script:
    - npm install
    - npm test
  only:
    - main
    - merge_requests

위 설정은 `main` 브랜치나 머지 리퀘스트에 변경사항이 푸시될 때마다 `npm install`과 `npm test`를 실행하도록 합니다. `npm test`가 실패하면 파이프라인이 실패하고, `main` 브랜치로의 머지를 막을 수 있습니다.

이처럼 서버 측 Git hooks는 프로젝트의 코드 베이스를 안전하게 보호하고, 모든 팀원이 높은 품질 기준을 준수하도록 강제하는 데 필수적인 역할을 합니다.

Image by geralt on Pixabay

Git Hooks 사용 시 고려사항 및 베스트 프랙티스

Git hooks는 강력한 도구이지만, 효과적으로 사용하기 위해서는 몇 가지 고려사항이 있습니다.

• 성능 최적화: Hook 스크립트가 너무 오래 실행되면 개발자의 워크플로우를 방해할 수 있습니다. 특히 `pre-commit` hook은 가급적 빠르게 완료되도록 최적화해야 합니다. `lint-staged`처럼 변경된 파일에 대해서만 작업을 수행하도록 하여 불필요한 연산을 줄이는 것이 좋습니다.
• 일관성 유지: `.git/hooks` 디렉토리는 로컬에만 존재하므로, 팀원 간에 hooks를 공유하고 일관성을 유지하는 것이 중요합니다. Husky와 같은 도구를 사용하면 `package.json`에 정의하여 Git으로 관리하고 쉽게 공유할 수 있습니다.
• 명확한 피드백: Hook이 실패했을 때 개발자에게 어떤 문제가 발생했는지 명확하고 이해하기 쉬운 메시지를 제공해야 합니다. 이는 문제를 빠르게 해결하고 개발 효율성을 높이는 데 도움이 됩니다.
• 우회 옵션 (`--no-verify`): Git은 `git commit --no-verify` 또는 `git push --no-verify` 옵션을 통해 hooks를 강제로 우회할 수 있는 기능을 제공합니다. 이는 비상 상황이나 특정 테스트를 건너뛰어야 할 때 유용하지만, 남용될 경우 코드 품질 관리가 무의미해질 수 있으므로 신중하게 사용해야 합니다.
• CI/CD와의 조화: Git hooks는 CI/CD 파이프라인을 대체하는 것이 아니라 보완하는 관계입니다. hooks는 로컬에서 빠른 피드백을 제공하여 초기 단계에서 문제를 걸러내고, CI/CD는 더 광범위하고 복잡한 통합 테스트, 배포 검증 등을 수행하여 최종적인 코드 품질을 보장합니다.

마무리하며

Git hooks는 개발 프로세스에 코드 품질 관리를 자동화하고 개발 생산성을 향상시키는 데 매우 효과적인 도구입니다. `pre-commit` hook을 활용하여 로컬에서 린팅, 포맷팅, 간단한 테스트를 자동화하고, 서버 측 hooks나 CI/CD를 통해 팀 전체의 코드 품질 표준을 강제함으로써, 개발 팀은 더 안정적이고 유지보수가 용이한 코드를 만들어낼 수 있습니다.

처음에는 설정이 다소 복잡하게 느껴질 수 있지만, Husky와 lint-staged 같은 도구를 활용하면 비교적 쉽게 적용할 수 있습니다. 오늘부터 Git hooks를 여러분의 프로젝트에 도입하여 코드 품질을 한 단계 끌어올려 보세요!

Git hooks를 사용해본 경험이 있으신가요? 어떤 방식으로 활용하고 계신지, 혹은 어떤 어려움을 겪으셨는지 댓글로 자유롭게 공유해주세요!