Git + Jira — 브랜치·커밋·PR에 이슈 키 연결하기

Sun, 07 Jun 2026 00:00:00 +0900

코드 변경에 이유를 남기는 방법

6개월 전에 작성한 코드를 보면서 “이게 왜 있지?“를 되묻는 경험이 있다면, 이 글이 그 문제를 해결해 준다.

Git 커밋 메시지와 Jira 이슈를 연결하면 코드 한 줄이 어떤 맥락에서 생겼는지 항상 추적할 수 있다.

연동의 핵심: 이슈 키

모든 것은 이슈 키 하나로 연결된다.

이슈 키 형식: {프로젝트 키}-{번호}
예) BLOG-42

이 키를 브랜치명, 커밋 메시지, PR 어디에든 넣으면 Jira가 자동으로 해당 이슈와 연결한다.

브랜치 네이밍

git switch -c feature/BLOG-42-add-comment-api

패턴: {type}/{이슈키}-{설명}

feature/BLOG-42-add-comment-api ← 기능 추가
bugfix/BLOG-37-fix-jwt-expiry ← 버그 수정
refactor/BLOG-55-split-service ← 리팩터링

이슈 키가 앞에 있으면 브랜치 목록에서 어떤 이슈와 연결됐는지 바로 보인다.

커밋 메시지

git commit -m "feat(comment): 댓글 생성 API 구현 BLOG-42"

커밋 끝에 이슈 키를 붙이는 것만으로 Jira가 연결을 감지한다.

조금 더 자세히 쓰고 싶다면:

git commit -m "feat(comment): 댓글 생성 API 구현

- POST /api/comments 엔드포인트 추가
- 댓글 내용 500자 유효성 검증

BLOG-42"

Smart Commits — 커밋 메시지로 Jira 이슈 상태를 자동으로 바꿀 수도 있다.

# 작업 시작 시 이슈를 In Progress로
git commit -m "feat: 댓글 API 작업 시작 BLOG-42 #in-progress"

# 완료 시 Done으로
git commit -m "feat: 댓글 API 완료 BLOG-42 #done"

PR 작성

제목: [BLOG-42] feat(comment): 댓글 생성 API 구현

PR 본문에는 이슈 링크를 추가한다:

## 관련 이슈
- Jira: [BLOG-42](https://your-domain.atlassian.net/browse/BLOG-42)
- Closes BLOG-42

## 변경 내용
- POST /api/comments 엔드포인트 추가
- 댓글 내용 500자 유효성 검증

## 테스트
- [ ] 댓글 생성 정상 응답
- [ ] 빈 내용 검증

Closes BLOG-42를 적으면 PR이 머지될 때 이슈가 자동으로 Done 처리된다.

GitHub for Jira 앱 연동

브랜치·커밋·PR이 Jira 이슈 페이지에서 바로 보이려면 앱 연동이 필요하다.

1. Jira → Apps → 앱 탐색
 → "GitHub for Atlassian" (by Atlassian) 설치

2. GitHub 계정 연결
 → Jira와 다른 구글 계정이어도 무관
 → OAuth 토큰 기반이라 계정 종류 상관없음

3. 연결할 레포 선택 → 승인

연동 후 Jira 이슈 페이지:

Development 패널:
 ├── Branches (1) : feature/BLOG-42-add-comment-api
 ├── Commits (3) : 관련 커밋 목록
 └── Pull Requests : [Open] 댓글 생성 API

이슈 하나에서 관련 코드 변경 전체를 볼 수 있다.

실전 워크플로우 요약

1. Jira에서 이슈 생성 → BLOG-42
2. 브랜치 생성 → feature/BLOG-42-add-comment-api
3. 커밋 → "feat: 구현 BLOG-42"
4. PR → [BLOG-42] feat: 댓글 API / Closes BLOG-42
5. 머지 → 이슈 자동 Done

혼자 쓸 때는 이 흐름을 다 지키기보다 브랜치명 + 커밋에 이슈 키만 챙겨도 충분하다. 나중에 git log에서 이슈 키로 검색하면 그 작업의 전체 맥락을 찾을 수 있다.

다음 편에서는 Slack과 연동해서 Jira + GitHub 알림을 한 곳에 모으는 방법을 다룬다.

Branch on kastori