릴리스 태그를 만드는데 -a 옵션을 빼먹으면 안 되는 이유

문제 발생

릴리스마다 git tag v1.2.0으로 태그를 만들어왔는데, 나중에 git show v1.2.0으로 그 태그의 정보를 보려 하니 태그 자체에 대한 메타데이터(누가 언제 왜 태그를 만들었는지)가 전혀 없이 그냥 특정 커밋만 가리키고 있었습니다.

원인 분석

Git의 태그에는 두 종류가 있습니다.

• Lightweight 태그(git tag v1.2.0): 특정 커밋을 가리키는 **이름표(포인터)**일 뿐입니다. 태그 자체는 Git 객체로 별도로 존재하지 않고, 그냥 브랜치처럼 커밋 해시를 가리키는 참조입니다 — 태그를 만든 사람, 시각, 메시지 같은 정보가 전혀 없습니다.
• Annotated 태그(git tag -a v1.2.0 -m "릴리스 메시지"): Git 객체 데이터베이스에 독립된 태그 객체가 만들어집니다 — 태그를 만든 사람, 이메일, 날짜, 메시지, 그리고 (선택적으로) GPG 서명까지 포함할 수 있습니다. git show v1.2.0으로 이 정보를 확인할 수 있고, git describe도 annotated 태그를 우선적으로 찾습니다.

릴리스처럼 "이 시점이 공식적으로 어떤 버전이었다"를 기록하는 태그는, 나중에 누가 언제 왜 릴리스했는지 추적할 수 있어야 하므로 annotated 태그가 실질적으로 더 유용합니다.

해결 방안

1. 릴리스/배포 태그는 항상 -a(annotated)로 만듭니다.

git tag -a v1.2.0 -m "v1.2.0: 검색 성능 개선, 결제 버그 수정"
git push origin v1.2.0

2. GPG로 서명된 태그(-s 옵션)까지 쓰면, 그 태그가 정말 신뢰할 수 있는 사람이 만든 것인지 암호학적으로 검증할 수도 있습니다 — 오픈소스 프로젝트의 공식 릴리스에서 흔히 쓰이는 방식입니다.
3. 가벼운(임시) 로컬 마킹 용도(예: 잠깐 특정 커밋을 표시해두고 나중에 지울 것)라면 lightweight 태그로도 충분합니다 — 모든 태그를 무조건 annotated로 만들 필요는 없고, 그 태그가 "영구적인 기록으로 남아야 하는가"가 기준입니다.
4. 태그는 기본적으로 git push로 원격에 전파되지 않습니다 — git push origin <태그이름> 또는 git push --tags로 명시적으로 push해야 다른 사람도 볼 수 있습니다. 태그를 만들었는데 CI가 그걸 못 봤다면 이 단계를 빠뜨렸을 가능성이 높습니다.

공식 문서

• Pro Git Book: Git Basics — Tagging