협업과 자동화를 위한 Git 커밋 메시지 컨벤션 완벽 정리

협업과 파이프라인(CI/CD)을 고려한 커밋 메시지 컨벤션 가이드

Conventional Commits 기반 실무 커밋 메시지 규칙 및 이슈 트래커 연동 총정리

개발을 하다 보면 커밋 메시지를 fix, 수정함, asdf처럼 대충 적고 싶은 유혹에 빠지곤 합니다. 하지만 시간이 지나 내가 만든 코드를 다시 보거나, 팀원들과 협업할 때 잘 작성된 커밋 메시지는 코드만큼이나 강력한 문서가 됩니다.

오늘은 현업에서 가장 표준적으로 쓰이는 Conventional Commits를 바탕으로, 실무 파이프라인(CI/CD, Semantic Release) 및 이슈 트래커 연동까지 고려한 확장형 커밋 메시지 규칙을 정리해 보았습니다.

1. 커밋 메시지의 기본 3단계 구조

커밋 메시지는 기본적으로 제목(Header), 본문(Body), 꼬리말(Footer) 3개 영역으로 나뉩니다.

이때 가장 중요한 규칙은 각 영역 사이에 '빈 줄(Empty line)'을 한 줄씩 두어 구분하는 것입니다.

type(scope): subject

body (선택 사항)

footer (선택 사항)

2. 제목(Header) 작성법: Type과 Scope

제목은 type(scope): subject 형태로 작성하여, 커밋로그 한 줄만 보고도 어떤 변경인지 한눈에 파악할 수 있게 합니다.

📌 주요 커밋 타입 (Types)

타입 설명 작성 예시
feat 새로운 기능 추가 feat(auth): 카카오 소셜 로그인 연동
fix 버그 수정 fix(order): 결제 시 세션 만료 오류 수정
perf 성능 개선 (쿼리 튜닝, 렌더링 최적화) perf(db): 회원 목록 인덱스 적용 및 최적화
refactor 리팩토링 (기능 변경 없이 코드 구조 개선) refactor(user): 회원가입 Validation 분리
docs 문서 수정 (README, API 스펙 등) docs(api): Swagger 문서 구성 최신화
style 코드 포맷팅, 세미콜론 누락 등 (로직 변경 X) style: 들여쓰기 4 spaces -> 2 spaces 변경
test 테스트 코드 추가 또는 수정 test(user): 회원가입 유닛 테스트 추가
chore 빌드 설정, 패키지 관리 등 잡다한 작업 chore: npm 패키지 버전 업데이트
ci CI/CD 파이프라인 관련 설정 변경 ci: GitHub Actions 배포 스크립트 수정
💡 Scope(범위) 팁!
fix(admin): ... 나 feat(api): ... 처럼 변경이 발생한 모듈이나 서비스명을 괄호 안에 적어주면, 여러 스택이나 서비스를 함께 다루는 프로젝트에서 로그를 훑어볼 때 매우 유용합니다.

3. 실무에서 꼭 지켜야 할 핵심 규칙 7가지

  1. 제목, 본문, 꼬리말 사이에는 반드시 빈 줄을 둡니다.
  2. 제목은 50자 이내로 간결하게 작성합니다.
  3. 제목 끝에는 마침표(.)를 찍지 않습니다.
  4. 영문 제목 작성 시 명령문/동사원형으로 시작합니다. (예: Add O, Added X)
  5. 본문은 한 줄당 72자 내외로 줄바꿈을 해줍니다.
  6. 본문에는 '어떻게(How)'보다 '무엇을, 왜' 변경했는지 기술합니다. (How는 코드가 말해주기 때문!)
  7. 꼬리말에는 이슈 번호 및 하위 호환성 변경 사항을 명시합니다.

4. 꼬리말(Footer) 작성 시 주의할 디테일

💥 BREAKING CHANGE (하위 호환성 파괴)
기존 API 스펙이 바뀌거나 DB 컬럼이 삭제되어 하위 호환성이 깨지는 변경이 있다면 꼬리말에 반드시 명시해야 합니다. Semantic Release 같은 자동 버저닝 도구가 이를 감지해 Major 버전(v1.0.0 -> v2.0.0)을 자동으로 올리는 기준이 됩니다. 
BREAKING CHANGE: /api/v1/user/profile 응답 객체 구조가 변경됨
🔗 이슈 트래커 연동 (Closes, Fixes, Resolves)
GitHub 이슈와 커밋을 연동할 때 주의할 점 2가지가 있습니다.
  • 기본 브랜치 머지 시점 동작: Closes: #12 키워드는 작업 브랜치가 아닌 main(기본 브랜치)에 머지되는 순간 이슈를 자동으로 닫습니다. (Feature 브랜치에 올려둔 동안은 단순 링크/참조 역할만 수행)
  • 다중 이슈 닫기 규칙: 여러 이슈를 동시에 닫을 때는 콤마 나열이 아니라 키워드를 반복해야 정상 동작합니다.
  • ⭕ 올바른 예: Closes #34, Closes #23
  • ❌ 잘못된 예: Closes #34, #23 (첫 번째 이슈만 닫힘!)

5. 한눈에 보는 실전 작성 예시

✅ 간단한 커밋 (제목만)

git commit -m "feat(auth): Google OAuth2 로그인 기능 추가"

✅ 풀 포맷 커밋 (제목 + 본문 + 꼬리말)

feat(user): 프로필 이미지 업로드 API 구현

- S3 버킷 연동 및 5MB 이하 이미지 파일 유효성 검증 추가
- 업로드 실패 시 예외 처리 및 에러 코드 매핑

BREAKING CHANGE: /api/v1/user/profile 응답 객체 구조가 변경됨
Closes #42, Closes #45

6. 팀 프로젝트를 위한 커밋 템플릿 설정

팀원들과 매번 컨벤션을 체크하기 어렵다면, 프로젝트 루트에 템플릿 파일을 생성해 누구나 쉽게 표준 양식을 불러오도록 설정할 수 있습니다.

1) .github/commit_template.txt 파일 생성

# <type>(<scope>): <subject> (제목 50자 이내, 마침표 금지)
# 타입: feat, fix, perf, refactor, docs, style, test, chore, ci
# 예시: feat(auth): 카카오 로그인 추가

# [본문] 무엇을, 왜 변경했는지 설명 (한 줄 72자 내외 줄바꿈)


# [꼬리말] 하위 호환성이 깨지는 변경이 있을 경우 작성 (선택)
# BREAKING CHANGE: 

# [꼬리말] 관련 이슈 닫기 (여러 개일 경우 키워드 반복)
# Closes #

2) Git에 템플릿 등록 명령어 실행

git config --local commit.template .github/commit_template.txt

댓글

댓글 쓰기

이 블로그의 인기 게시물

[문서] excel 체크박스 삭제

가끔 사이트 내용 복사해서 엑셀에 붙여넣기 하면 체크박스도 복사가 됨. 지우고 싶은데 쉽게 그냥 지워지지 않음. 지우는 방법은 Ctrl + G 누르면 이동이라는 박스 나옴. 거기 하단을 보면 옵션 있음. 옵션 누르고 종류에서 개체 선택하고 확인 누르면  체크박스가 선택 되어짐. 그러면 Delete로 삭제하면됨.  참고 Link :  https://pencil1.tistory.com/112
자세한 내용 보기

[DB] MySQL 백업 / 복원

이미지
1. Heidi SQL 1). 백업 가. 해당 DB 우클릭 >> 데이터베이스를 SQL로 내보내기 클릭.  (HeidiSQL 9.4) 나. 테이블 도구 >> 데이터베이스 : 생성                        테이블 : 생성                        데이터 : 삭제 + 삽입 (기존 데이터 초기화)                        출력 : 단일 .SQL 파일                        파일명 : 원하는이름으로... 다. 내보내기 클릭 후 지정된 폴더에 백업파일 생성. 2). 복원 가. 파일(메뉴) >> SQL 파일 실행 >> 해당 백업파일 열기.  끝. 3). 개별 테이블 백업 및 복원 (위에 이미지 참고) 가. 해당 테이블 우클릭 >> 데이터베이스를 SQL로 내보내기 클릭. 나. 테이블 도구 >> 데이터베이스 : 없음 (생성 체크하면 DB와테이블이 같이 만들어짐)                        테이블 : 생성                        데이터 : 삭제 + 삽입 (기존 데이터 초기화)      ...
자세한 내용 보기

[DB] MySQL 사용자(USER) 생성,삭제,권한부여 하기

MS SQL은 DB별로 USER 생성 사용 했는데 AWS RDS MySQL은 루트계정(최상위계정)으로만 사용을 해서 잊고 있다가 DB별로 USER 사용하는 MySQL에 잠깐 당황을 해서 (루트계정으로 실행되는 명령어가 안되어서.....) 알고자 씀. 1. 먼저 mysql DB를 선택하고 사용자 확인하기. use mysql; select host, user, password from user; (select * from user; 는 컬럼이 넘 많아서....) 2. 사용자(user) 추가 create user 'userID'@'%' identified by 'userpassword'; user 테이블 host 컬럼보면 값이 % ,localhost가 있는데 %는 외부접근 localhost는 내부접근 그러므로 위에 명령어는 외부접근이 되는 사용자 계정. 또는 '111.222.%' IP 주소가 111.222.xxx.xxx 로 시작하는 IP 대역        '111.222.333.444' 는 111.222.333.444로 시작하는 특정 IP 외부 허용. 또는 insert into user (host,user,password) values('%','userID',password('userpassword'));         FLUSH PRIVILEGES; FLUSH PRIVILEGES란? INSERT, DELETE, UPDATE를 통해 사용자를 추가, 삭제, 권한 변경 등을 수행하였을 때 이 변경 사항을 반영하기 위하여 사용한다. 이 때 FLUSH PRIVILEGES는 grant 테이블을 reload함으로서 변경 사항을 즉시 반영하도록 한다. 그런데 이 FLUSH PRIVILEGES는 굉장히 성능에 영향을 준다. 특히 습관적으로 FLUSH PRIVILEGES를 사용하는 경우가 있는데 이는 엄청난 부하가...
자세한 내용 보기