git commit 에 티켓 문서 주소 연동하기 (Autolink & Commit Hook)

아틀라시안의 Bitbucket과 Jira를 사용하여 업무를 하다가,

깃허브와 노션을 사용하여 업무하는 환경으로 이직하게 되었다.

 

이 때 Bitbucket 에서 커밋 제목이던 내용에 Jira의 티켓 번호를 쓰면

자동으로 Jira의 티켓 문서 URL 이 링크되던 기능이 떠올랐고,

 

깃허브와 노션 환경에서도 사용해보고자 해당 게시글을 작성해본다.

 

0. 목표 정리

1. 커밋 제목에 ITEM-123 / N-7b3c... 같은 짧은 토큰만 써도
2. GitHub 웹에서는 자동으로 Notion 페이지로 링크가 걸리고
3. GitHub Desktop / Visual Studio에서도 커밋 상세를 보면 클릭 가능한 URL이 있어서 바로 열 수 있게 만들기

---

1. GitHub Autolink 설정

해당 방법을 사용하면 정확하게 우리가 원하던 방식으로 링크를 걸 수 있지만,

깃허브 웹 UI 에서만 작동을 하게 된다.

 

이 방법으로 깃허브 웹에서의 오토링크를 활성화하고

다른 도구들에서는 아래 2번 방법으로 자동으로 커밋 내용에 링크가 걸리도록 설정한다.

 

깃허브 레포지토리에 접속한 다음.

1. Settings → Integrations → Autolink references → Add new
2. 예시 1: Notion Unique ID(ITEM-123)용
   • Reference prefix: ITEM-
   • Type: Numeric  (숫자만 인식하므로)
   • Target URL:
     https://notion.so/ITEM-<num>
   → 커밋/PR/이슈 제목·본문에 ITEM-123만 써도
   GitHub 웹 UI에서 자동으로 https://notion.so/ITEM-123로 링크됨.

---

2. prepare-commit-msg Hook

이제 로컬 클라이언트에서도 클릭 가능한 URL이 생기게,
커밋 때 토큰을 보고 본문 맨 아래에 URL을 자동으로 붙여주는 과정

 

2-1. 전역 훅 디렉터리 만들기 

mkdir -p ~/.git-hooks
git config --global core.hooksPath ~/.git-hooks

 

2-2. 훅 스크립트 작성

~/.git-hooks/prepare-commit-msg 파일 만들고

#!/bin/sh
MSG_FILE="$1"

# 이미 Notion URL이 있으면 아무 것도 안 함 (중복 방지)
if grep -q 'https://notion.so/' "$MSG_FILE"; then
  exit 0
fi

TEXT=$(cat "$MSG_FILE")

# ITEM-숫자 패턴 (예: ITEM-123)
ITEM_IDS=$(printf '%s\n' "$TEXT" | grep -Eo 'ITEM-[0-9]+' | sort -u 2>/dev/null)

# N-32자리 hex 패턴 (예: N-7b3cf13ed2a44733aaf6e32136c28c3b)
N_IDS=$(printf '%s\n' "$TEXT" | grep -Eo 'N-[0-9a-fA-F]{32}' | sort -u 2>/dev/null)

# 둘 다 없으면 종료
if [ -z "$ITEM_IDS" ] && [ -z "$N_IDS" ]; then
  exit 0
fi

# 본문 맨 아래에 Refs 블록 추가
{
  echo ""
  echo "Refs:"
  for id in $ITEM_IDS; do
    echo "  - https://notion.so/$id"
  done
  for id in $N_IDS; do
    clean=$(printf '%s' "$id" | sed 's/^N-//')
    echo "  - https://notion.so/$clean"
  done
} >> "$MSG_FILE"

 

• 커밋 제목에 ITEM- 이 들어간 것 발생 시
  • feat: add WIP view ITEM-123
  • [ITEM-123] 커밋 제목 입니다.
• 커밋 확정 시, 메시지 맨 아래에 자동으로:

Refs:
     - https://notion.so/ITEM-123

같은 블럭이 들어감.

• GitHub Desktop / Visual Studio: 이 URL을 그대로 클릭 가능

---

3. 팀원들 모두 다같이 쓰게 하려면?

 

1) 위 훅 스크립트를 특정 경로에 넣고 레포에 저장.

2) 설치용 스크립트를 특정 경로에 넣고 레포에 저장.

 

경로 설명

#루트 경로
your-repo/

     .git-hooks/
         prepare-commit-msg # ← 위에서 만든 훅 스크립트 (tracked)
   
     scripts/
          setup-hooks.sh # ← 설치용 스크립트

 

scripts/setup-hooks.sh:

#!/bin/sh
set -e

# 레포 루트
ROOT_DIR=$(git rev-parse --show-toplevel)

# 훅 디렉터리 / 파일 경로
HOOK_DIR="$ROOT_DIR/.git-hooks"
HOOK_FILE="$HOOK_DIR/prepare-commit-msg"

# 훅 파일 존재 확인
if [ ! -f "$HOOK_FILE" ]; then
  echo "❌ hook file not found: $HOOK_FILE"
  exit 1
fi

# 실행 권한 보장
chmod +x "$HOOK_FILE"

# 이 레포의 hooksPath 를 .git-hooks 로 설정 (레포 기준 상대 경로)
git config core.hooksPath .git-hooks

echo "✅ prepare-commit-msg 활성화됨 (.git-hooks/prepare-commit-msg)"
echo "✅ core.hooksPath = .git-hooks 로 경로 설정됨 (이 레포의.git/config에 저장)"

 

3) 팀원이 할 일

1. Git 설치 시 같이 깔린 Git Bash 실행 (그냥 sh 를 실행할 수 있는 환경이면 상관없음)
2. 레포 루트로 이동 후:

cd /c/…/your-repo        # 경로 맞게
sh scripts/setup-hooks.sh

(또는 PowerShell에서 sh scripts/setup-hooks.sh 해도 됨. Git 설치되어 있으면 sh 있음.)

한 번 실행 후에는:

• core.hooksPath = .git-hooks가 이 레포의 .git/config에 저장
• 그 이후부터는 어디서 커밋하든
  이 레포에서 git commit이 실행될 때마다 prepare-commit-msg가 자동으로 동작