Commit on kastori

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 알림을 한 곳에 모으는 방법을 다룬다.

커밋 메시지를 잘 쓴다는 것 — Conventional Commits 실전 가이드

Sat, 06 Jun 2026 00:00:00 +0900

git log에 남는 것들

git log --oneline

a3f21c9 수정
b12e8f1 fix
c94d3a2 asdf
d77f0e1 작업 완료
e23b1c7 ㅁㄴㅇ

6개월 전 내가 쓴 커밋들이다. 뭘 고쳤는지, 왜 고쳤는지 전혀 알 수 없다. 커밋 메시지는 코드의 히스토리이고, 미래의 나(또는 동료)에게 보내는 메모다.

Conventional Commits 형식

<type>(<scope>): <subject>

[optional body]

[optional footer]

# 실제 예시
feat(auth): Google OAuth2 소셜 로그인 추가

기존 이메일/비밀번호 로그인과 병행 사용 가능.
Google Cloud Console에서 OAuth 앱 등록 필요.

Closes #123

type 종류

type	언제 쓰나	버전 영향
`feat`	새 기능 추가	Minor ↑
`fix`	버그 수정	Patch ↑
`refactor`	리팩터링 (기능 변화 없음)	없음
`test`	테스트 추가/수정	없음
`docs`	문서 변경	없음
`style`	코드 포맷팅 (로직 무변화)	없음
`chore`	빌드, 패키지, CI 설정	없음
`perf`	성능 개선	Patch ↑

좋은 커밋 메시지의 조건

제목은 50자 이하, 명령형으로

# ✅ 좋음
feat(order): 주문 취소 API 추가
fix(auth): 로그아웃 후 토큰 무효화 안 되는 버그 수정

# ❌ 나쁨
feat(order): 주문 취소 기능을 구현했습니다 (과거형, 너무 김)
fixed bug (type 없음, 뭘 고쳤는지 모름)

body는 “왜"를 설명한다

refactor(payment): 결제 전략 패턴으로 분리

기존 PaymentService에 if/else로 결제 수단이 추가될 때마다
코드 수정이 필요했음. 전략 패턴 도입으로 OCP 달성.
새 결제 수단 추가 시 PaymentStrategy 구현체만 추가하면 됨.

what(무엇을 바꿨는가)은 코드 diff를 보면 안다. body에는 **why(왜 바꿨는가)**를 쓴다.

Breaking Change

하위 호환성이 깨지는 변경은 반드시 명시한다.

feat!: 사용자 API 응답 형식 변경

BREAKING CHANGE: userId 필드가 id로 변경됨.
기존 클라이언트는 필드명 수정 필요.

feat!의 !가 Breaking Change를 의미한다. SemVer에서 Major 버전 업 트리거.

커밋 단위 원칙

하나의 커밋 = 하나의 목적

# ✅ 좋음 — 목적이 명확한 단위
git commit -m "feat(user): 회원가입 엔티티 추가"
git commit -m "feat(user): 회원가입 서비스 로직 구현"
git commit -m "feat(user): 회원가입 API 엔드포인트 추가"
git commit -m "test(user): 회원가입 서비스 단위 테스트"

# ❌ 나쁨 — 여러 목적이 섞임
git commit -m "회원가입 기능 구현 및 버그 수정 및 테스트"

WIP 커밋 처리

작업 중간에 저장해야 할 때는 WIP 커밋을 만들고, PR 전에 정리한다.

# 작업 중 임시 저장
git commit -m "WIP: 결제 API 작업 중"

# PR 전에 squash로 깔끔하게 정리
git rebase -i HEAD~3
# WIP 커밋들을 squash해서 하나로 합치기

squash는 이 시리즈 마지막 편(고급 명령어)에서 다룬다.

CHANGELOG 자동 생성

Conventional Commits 형식을 지키면 CHANGELOG를 자동 생성할 수 있다.

# conventional-changelog 설치
npm install -g conventional-changelog-cli

# CHANGELOG.md 생성
conventional-changelog -p angular -i CHANGELOG.md -s

# CHANGELOG

## [1.3.0] - 2026-06-04

### Features
- **auth**: Google OAuth2 소셜 로그인 추가 (#123)
- **order**: 주문 취소 API 추가 (#124)

### Bug Fixes
- **auth**: 로그아웃 후 토큰 무효화 버그 수정 (#125)

커밋 메시지 하나하나가 릴리즈 노트가 된다. 다음 편에서는 이 커밋들을 담는 PR을 잘 쓰는 법을 다룬다.