커밋 메시지 맨 앞에 이슈 키 — Jira·GitLab 연동 2주 해보니

지난 글에서 Jira 셋팅 11일 기록을 적었습니다. 상태를 7개로 짰다가 3개로 줄인 얘기였어요.

이번 편은 그다음입니다. 커밋 메시지랑 Jira 이슈를 묶는 일.

설정 자체는 10분이면 끝납니다. 진짜 문제는 그 뒤에 있었어요.

---

왜 묶어야 하나

석 달 전 코드를 보다가 이런 생각 해보신 적 있으시죠.

"이거 왜 이렇게 짜놨지?"

git log를 열어봅니다. 커밋 메시지가 이렇게 나와요.

수정
README 수정
버그 픽스
로직 변경

아무것도 안 나옵니다. 누가 왜 요청했는지, 그래서 해결은 됐는지, 어디에도 없어요.

이걸 묶어두면 커밋 하나에서 요청 → 논의 → 확인까지 전부 따라갈 수 있습니다. 저희는 과제 품질관리 요구사항에 "요구사항 변경 이력 추적"이 들어 있어서 어차피 해야 했는데, 해놓고 보니 그 증빙보다 일상적인 쓸모가 더 컸습니다.

---

원리는 어이없을 만큼 단순하다

GitLab이 커밋 메시지를 긁어서 이슈 키 패턴을 찾습니다. 찾으면 그 Jira 이슈에 댓글로 커밋 기록을 자동으로 답니다.

설정은 GitLab–Jira 연동 한 번 걸어두면 끝이고, 그 뒤로는 커밋 메시지에 키만 넣으면 됩니다. 프로젝트별로 뭘 더 할 게 없어요.

git commit -m "DEV-75 README 작성 (프로젝트 개요·빌드·배포 규칙)"

push하고 1분쯤 지나면 해당 이슈 댓글에 이런 게 생깁니다.

○○○ mentioned this issue in a commit on branch feature/DEV-75-readme

[이미지 삽입] 키워드: "Jira 이슈 커밋 연동 댓글" / 설명: 실제 이슈 화면에서 커밋 기록이 댓글로 자동 등록된 부분 캡처 (저장소명·계정명은 가려서)

---

여기서 다들 걸립니다

가이드를 배포하고 2주 돌려보니, 연결 안 되는 커밋이 계속 나왔습니다. 원인은 셋 중 하나였어요.

쓴 것 결과

DEV-75 README 작성	✅ 연결됨
README 수정	❌ 키가 없음
dev-75 수정	❌ 소문자 — 안 될 수 있음
DEV75 수정	❌ 하이픈 없음

제일 많았던 게 소문자였습니다. 사람은 dev-75나 DEV-75나 같은 걸로 읽는데 기계는 아니거든요. 저도 한 번 당했습니다. 커밋하고 Jira 열었는데 아무것도 없어서 연동이 깨진 줄 알고 설정을 다 뒤졌어요. 소문자였습니다.

이미 push했는데 키를 빠뜨렸다면? 커밋을 고치려 들지 마세요. 히스토리 바꾸는 게 훨씬 귀찮습니다. 그냥 Jira 이슈 댓글에 커밋 해시를 손으로 적으면 됩니다. 어차피 목적은 추적이니까요.

커밋 하나가 이슈 두 개에 걸칠 때는 키를 둘 다 적으면 됩니다. 양쪽 이슈에 각각 댓글이 달립니다.

git commit -m "DEV-75 DEV-74 설정·문서 정리"

---

브랜치 이름에도 키를 넣었다

이건 자동 연동이랑은 상관없습니다. 순전히 사람이 보려고 넣는 거예요.

git checkout main
git pull origin main
git checkout -b feature/DEV-75-readme

형식은 feature/이슈키-작업요약으로 통일했습니다.

git branch 쳤을 때 내가 지금 무슨 이슈를 붙잡고 있는지 바로 보이는 게 생각보다 컸어요. 브랜치 서너 개를 왔다 갔다 하면 이름만으로는 헷갈리거든요.

자주 나온 오류 하나. already exists가 뜨면 같은 이름 브랜치가 이미 있는 겁니다. git checkout 브랜치명으로 그냥 이동하면 됩니다. 새로 만들 필요 없어요.

---

Closes 쓸 뻔했다가 접은 이유

여기가 이번 편에서 제일 중요한 부분입니다.

main 병합 커밋에 Closes 이슈키를 넣으면 Jira 이슈가 자동으로 완료 처리됩니다.

git merge --no-ff feature/DEV-75-readme -m "Closes DEV-75 README 작성"

처음엔 이거 좋다고 생각했어요. 병합하면 알아서 닫히니까 손이 덜 가잖아요.

안 쓰기로 했습니다.

이유는 저희 배포 구조에 있었습니다. main에 push하면 Jenkins가 5분 안에 운영 서버로 자동 배포됩니다. 그러니까 Closes를 쓰면 이 순서가 돼요.

병합 → 운영 배포 → 이슈 자동 완료

"배포됨"이랑 "제대로 동작함"은 다른 얘기입니다.

실제로 통합테스트 결함을 고칠 때 이걸 겪었어요. 로컬에서 통과한 수정 두 건이 운영 환경에서는 아니었습니다. 재검증을 안 했으면 "완료"로 찍혀서 아무도 다시 안 봤을 거예요.

그래서 규칙을 이렇게 잡았습니다.

• 화면 확인이 필요 없는 건 (문서, 설정, 리팩터링) → Closes 써도 됨
• 화면 확인이 필요한 건 → 일반 커밋으로 병합 → 운영에서 확인 → Jira에서 손으로 완료

손으로 누르는 게 번거로워 보이는데, 그 번거로움이 재검증을 강제하는 장치더라고요.

그리고 하나 더. 작업 중 커밋에는 절대 Closes를 쓰면 안 됩니다. 아직 확인도 안 끝났는데 이슈가 닫혀버립니다. Closes는 main 병합 커밋에서만요.

git 브랜치 머지 흐름도

 

---

feature 브랜치는 안전하다

처음에 개발자들이 제일 걱정한 게 이거였어요.

"push했다가 운영에 바로 나가는 거 아니에요?"

아닙니다. 배포는 main에 붙어 있지 feature 브랜치랑은 무관합니다. feature 브랜치는 몇 번을 push해도 운영에 아무 일도 안 일어나요.

이 한 줄을 가이드에 굵게 적어놨더니 커밋 빈도가 눈에 띄게 올라갔습니다. 다들 무서워서 묵혀두고 있었던 거죠.

---

매일 체크리스트 3줄

가이드를 아무리 잘 써도 안 읽습니다. 그래서 마지막 장을 세 줄로 줄였어요.

• 출근 후 — 내 이슈 확인, 오늘 할 이슈를 '진행 중'으로
• 커밋할 때 — 메시지 맨 앞에 이슈 키
• 퇴근 전 — 끝난 이슈 '완료', 진행 상황 댓글, 산출물 최종본 첨부

실제로 효과 본 건 가이드 본문이 아니라 이 세 줄이었습니다. 사람들이 기억하는 분량에는 한계가 있더라고요.

---

정리

• 연동 설정은 10분, 정착은 2주
• 이슈 키는 대문자 + 하이픈. 소문자가 제일 흔한 실수
• 키 빠뜨린 건 커밋 고치지 말고 댓글로 메우기
• Closes 자동 완료는 확인이 필요 없는 작업에만
• 가이드 분량보다 체크리스트 세 줄이 효과가 크다

다음 편에서는 여기에 Claude를 붙인 얘기를 적겠습니다. "지난주에 내가 완료한 이슈 뭐 있었지?"를 그냥 물어보면 답이 나오는데, 되는 것과 안 되는 게 꽤 갈립니다. 그 경계랑 쓰면서 정한 보안 규칙을 정리해볼 생각이에요.