[Git·GitOps 12] 태그와 릴리스: 배포한 커밋을 찾을 수 있게 만들기

운영에 어떤 코드가 올라갔는지 묻는데 “지난 금요일 main”이라고 답하면 재현하기 어렵습니다. 브랜치는 계속 이동하므로 배포 기준에는 고정된 커밋과 결과물 식별자가 필요해요. 태그는 그 커밋에 사람이 읽기 좋은 이름을 붙이는 출발점입니다.

main에 검토된 커밋이 있고 테스트가 통과한 상태를 전제로 합니다. 아래 v0.1.0이 이미 있으면 새 예제 버전 이름을 선택합니다. 다른 사람이 쓰는 릴리스 태그를 삭제하고 재사용하지 않습니다.

Git·GitOps 전체 연재 · 12 / 24

이 글의 목차

1. 정확한 커밋에 주석 태그를 만든다

git switch main
git pull --ff-only
git status --porcelain
git log -1 --oneline
git tag -a v0.1.0 -m "First training release"
git show v0.1.0
git rev-parse 'v0.1.0^{commit}'

가벼운 태그는 커밋을 가리키는 참조이고, 주석 태그는 작성 정보와 메시지를 가진 태그 객체를 만듭니다. ^{commit}은 주석 태그를 따라 실제 커밋을 확인하는 표기입니다. 자동화가 태그 객체 ID와 커밋 ID를 혼동하지 않도록 구분합니다.

태그 생성은 로컬 작업입니다. 원격으로 전달할 때에는 이번 태그를 명시해 푸시합니다. 불필요한 로컬 태그까지 전부 올리는 것보다 의도를 확인하기 쉬워요.

git push origin refs/tags/v0.1.0
git ls-remote --tags origin

릴리스는 태그에 배포 자료를 붙이는 서버 기능

GitHub나 Gitea의 Release 화면에서는 태그에 변경 내역과 파일을 연결할 수 있습니다. Git 태그만 푸시했다고 설치 파일, 테스트 로그, 이미지가 자동으로 생성되는 것은 아닙니다. CI가 어떤 결과물을 만들고 어디에 보관하는지 별도로 정합니다.

기록	예시	확인할 내용
코드 기준	v0.1.0과 커밋 ID	어떤 소스를 사용했는가
빌드 실행	CI 실행 번호와 URL	어떤 절차와 환경에서 만들었는가
파일 결과물	ZIP와 SHA-256	보관 중 파일이 바뀌지 않았는가
컨테이너	저장소 이름과 digest	실제로 어떤 이미지를 배포했는가

체크섬은 파일 일치 여부를 비교하는 값입니다. 공격자가 파일과 체크섬을 함께 바꾸는 상황까지 막으려면 신뢰할 수 있는 서명과 전달 경로가 필요합니다. 커밋 서명 또한 코드가 안전하다는 인증서가 아니라 서명 키와 기록의 관계를 확인하는 기능입니다.

버전 숫자에는 호환성 약속이 필요하다

Semantic Versioning의 MAJOR.MINOR.PATCH는 공개 API와 호환성 약속을 전제로 합니다. 호환성이 깨지면 major, 하위 호환 기능 추가는 minor, 호환 버그 수정은 patch를 올리는 방식입니다. 무엇을 공개 API로 보는지 정하지 않으면 숫자만 같은 모양으로 쓴다고 같은 의미가 되지 않습니다.

문서나 사내 설정 저장소는 날짜나 자체 릴리스 번호가 더 명확할 수도 있습니다. 어떤 규칙을 쓰든 한 번 배포한 이름이 다른 내용으로 바뀌지 않도록 보호 태그와 권한을 검토합니다. 변경이 필요하면 새 버전을 만듭니다.

태그에서 파일을 꺼내고 검증한다

mkdir -p dist
git archive --format=zip --output=dist/app-v0.1.0.zip v0.1.0
# Linux:
sha256sum dist/app-v0.1.0.zip

Windows PowerShell에서는 다음 명령으로 같은 알고리즘의 해시를 계산합니다. 출력 형식은 달라도 파일이 같으면 해시 값은 같습니다.

Get-FileHash .\dist\app-v0.1.0.zip -Algorithm SHA256

git archive는 Git에 기록된 파일을 내보냅니다. 미추적 파일과 런타임 데이터, 별도 LFS 서버의 실제 대용량 객체까지 모두 백업한다고 가정하지 않습니다. 배포 결과물은 테스트한 파일을 그대로 보관하고 환경별로 승격하는 방식으로 19편에서 연결합니다.

옵션은 git tag, 버전 규칙은 Semantic Versioning 공식 명세를 기준으로 설명했습니다.

이전 글 · [Git·GitOps 11] 팀 브랜치 전략과 Pull Request: merge·rebase의 선택 · 다음 글 · [Git·GitOps 13] 저장소 정리: gitignore·줄바꿈·LFS·비밀 값 · 연재 목록과 예제 파일