배포 릴리즈 관리, 진짜 알아보기 (Semantic Versioning · 릴리즈 태그 · 배포 자동화 · Semantic-release 완전 안내서)

개발을 한 지 꽤 되었는데도 “릴리즈 관리”는 막상 손대기 어려운 영역이었다.

로컬에선 잘 돌아가는데, 배포는 또 다른 세계고…

PR 만들고 Merge하고, 태그 달고, 배포 트리거하고, 버전 올리고, changelog 갱신하고…

 

심지어 SemVer(시맨틱 버전), 릴리즈 태그 전략, GitHub Release, CI/CD 파이프라인, semantic-release, rollback 전략까지 알아두면 좋지만, 이걸 한 번에 배운 적은 없었다.

 

그래서 이번 기회에 한 번 제대로 정리해보려고 한다. (흐름 위주로 !)

 

릴리즈 관리란 결국 뭐냐

한 줄로 말하면 이런 것 같다.

코드를 안정적으로 사용자에게 전달하기 위한 버전·변경·배포 흐름을 관리하는 것

 

이를 좀 더 실무스럽게 풀면

• 어떤 기능이 언제 릴리즈되었는지 흔적이 남아야 하고
• 변경 사항이 명확해야 하고 (changelog)
• 롤백이 쉬워야 하고
• 배포 과정이 자동화돼야 하고 (CI/CD)
• 버전 관리 규칙(SemVer)을 따라야 한다

릴리즈 관리를 잘하는 회사들은 공통적으로 “정해진 규칙에 따라 모든 게 자동화되어 있다”.

 

예를 들면,

PR → Merge → 태그 → GitHub Release → CI/CD 배포

이게 버튼 한 번도 누르지 않아도 자동으로 굴러간다.

이제부터 이런 걸 하나씩 이해해보자.

 

시맨틱 버전(Semantic Versioning) 이해하기

SemVer는 유명한 Node.js 개발자 Tom Preston-Werner(깃헙 공동 창업자)가 제안한 규칙이다. (나도 이전에 공부한 적이 있다)

 

버전은 이렇게 생겼다

MAJOR.MINOR.PATCH

그리고 버전의 의미는?

MAJOR	기존과 호환되지 않는 변경 (breaking change)
MINOR	기능 추가 (backward-compatible)
PATCH	버그 수정

 

예시로 보자면,

• 1.2.0 → 기능 추가
• 1.2.3 → 버그 수정
• 2.0.0 → 완전한 breaking change

이 규칙을 정확히 지키면 아주 좋은 점이 있다.

배포 버전만 보면 어떤 위험도가 있는지가 바로 드러난다

그래서 오픈소스, 기업용 시스템 모두 SemVer를 기본으로 사용한다.

 

릴리즈 태그는 왜 필요할까?

Git 태그(tag)는 “이 커밋이 릴리즈된 커밋이다”라는 표시다.

예를 들어 보자면,

v1.3.0
v1.3.1
v2.0.0

보통 이렇게 붙인다.

 

태그가 있으면 뭘 할 수 있냐면,

• 배포 기준 커밋을 명확하게 알 수 있다
• 버전 릴리즈 이력 관리가 쉽다
• 특정 버전으로 롤백하기 쉬워진다
• CI/CD에서 “태그를 기준으로 배포 트리거”를 만들 수 있다

추가로 GitHub에서는 태그 + 릴리즈 노트까지 만들어서 관리할 수 있다.

 

1. 태그 생성하기

• 간단한 태그 생성 - 현재 커밋에 태그를 지정함.

git tag <태그이름>

• 특정 커밋에 태그 생성 - 특정 커밋의 해시 값을 사용하여 태그를 지정함.

git tag <태그이름> <커밋해시>

• 주석이 있는 태그(annotated 태그) 생성 -a 옵션으로 주석과 함께 태그를 만든다.

git tag -a <태그이름> -m "<태그에 대한 설명>"

• -m 옵션을 사용하지 않으면 Git 편집기가 자동으로 실행됨. 

2. 태그 확인 및 사용하기

• 모든 태그 확인

git tag

• 특정 태그의 정보 확인

git show <태그이름>

• 태그를 사용하여 체크아웃 - 지정한 태그 시점으로 이동함.

git checkout <태그이름>

3. 태그 푸시하기

• 특정 태그만 푸시

git push origin <태그명>

• 모든 로컬 태그를 푸시

git push origin --tags

4. 태그 삭제하기

• 로컬 태그 삭제

git tag -d <태그이름>

• 원격 태그 삭제

git push origin :refs/tags/<태그명>

릴리즈 → 배포 자동화(CI/CD)

회사나 프로젝트마다 다르지만 기본 흐름은 크게 다르지 않다.

보통 이렇게 한다고 한다.

1. main/master 브랜치에 PR 머지됨
2. 릴리즈 봇 혹은 semantic-release가 “다음 버전”을 계산함
3. 태그 생성 (v1.4.0)
4. GitHub Release 자동 생성
5. 배포 파이프라인(CI/CD)이 태그를 기준으로 실행됨
6. 빌드 → 테스트 → 서버 배포 → 완료

즉, 사람이 하는 것은 PR을 머지하는 것뿐 나머지는 자동화인 것이다.

이걸 실무에 적용하면 릴리즈 실수가 거의 사라진다.

"사람이 클릭하는 순간 릴리즈 사고가 난다"

그래서 자동화는 필수다.

 

semantic-release는 뭐냐?

semantic-release는 말 그대로 자동 버전 관리 + 자동 릴리즈 + 자동 changelog 생성기이다.

https://github.com/semantic-release/semantic-release

GitHub - semantic-release/semantic-release: :package::rocket: Fully automated version management and package publishing

 

여기서 중요한 포인트!

semantic-release는 커밋 메시지를 기반으로 다음 버전을 판단함

예를 들면 다음과 같다.

feat: 새로운 기능 추가   → MINOR bump
fix: 버그 수정           → PATCH bump
feat!: API 변경(Breaking) → MAJOR bump

그리고 자동으로 다음과 같은 일을 해준다.

• 버전 올리고
• Git tag 생성하고
• GitHub Release 만들고
• CHANGELOG.md 작성하고
• 배포까지 이어지게 설정할 수 있다

정말로 아주 완전한 자동화다.

오픈소스에서는 거의 필수이고, 회사에서도 규모가 크면 이걸 도입한다고 한다.

 

커밋 규칙(Conventional Commits) 이해하기

semantic-release는 고정된 규칙을 사용한다.

feat: 기능 추가
fix: 버그 수정
perf: 성능 개선
refactor: 리팩토링
docs: 문서
test: 테스트
chore: 기타 작업

그리고 Breaking Change를 표시하려면 느낌표를 붙인다.

feat!: API 변경

이러면 자동으로 Major 버전으로 올라간다.

 

이 규칙은 Angular·Google·Chromium 등 여러 대형 프로젝트가 이미 채택했고 Ben Nadel, Addy Osmani(구글 개발자) 같은 유명 FE 개발자들도 실무에서 추천하는 방식이다.

 

릴리즈 + 배포 전체 흐름 예시 (실무에서 이렇게 굴러간다)

팀에서 semantic-release + GitHub Actions을 사용한다고 가정하면...

1. 개발자가 기능 작업 후 커밋 메시지 작성
2. feat: 대시보드 차트 드릴다운 기능 추가
3. PR 생성 → 코드 리뷰 → main에 머지
4. main에 머지되면 GitHub Actions가 semantic-release 실행
5. semantic-release가 자동으로 판단
   • 버전: 1.5.0 → 1.6.0
   • 태그 생성: v1.6.0
   • changelog 업데이트
   • GitHub Release 작성
6. 태그 이벤트가 트리거되어 CD 파이프라인이 실행
   → 배포 성공
7. 릴리즈 노트는 자동 생성된 상태로 GitHub에 남음

 

이 케이스에서는 아무도 버전 관리 안 한다.
아무도 GitHub Release 안 만든다.
아무도 changelog 안 만든다.

그냥 모든 것이 자동인 것이다.

 

롤백 전략은 어떻게 하냐?

태그 릴리즈 방식에서는 롤백이 아주 쉽다.

예를 들면,

git checkout v1.5.0

그리고 그 버전에 맞춘 태그 기준으로 CI/CD를 재실행하면 끝이다.

 

Kubernetes나 AWS ECS/Fargate 같은 곳에서는 이미 이전 버전 아티팩트(image 등)가 남아 있으니까 버튼 하나로 롤백되기도 한다.

 

실무에서 많이 쓰는 릴리즈 관리 전략

몇 가지 패턴이 유명하다.

GitHub Flow

• main에 직접 머지
• 태그 기반 릴리즈
• 배포 자동화 필수

스타트업이나 빠른 배포에 적합.

GitLab Flow

• 환경별 브랜치(prod, stage)
• 태그는 prod 기준
• Enterprise 환경에서 많이 씀

Trunk-Based Development

• 모든 개발은 아주 작은 단위로 main에 바로 들어감
• Google/Netflix에서도 이 방식 사용
• 릴리즈 자동화가 핵심

 

Vite + Node + Semantic-release 간단 예제

release.config.js

module.exports = {
  branches: ["main"],
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/git"
  ]
};

.github/workflows/release.yml

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

이러면 main에 PR이 머지되는 순간 자동 배포가 돌아간다.

 

참고 자료들.... 🤩

• SemVer 공식 문서
  https://semver.org
• Tom Preston-Werner(깃헙 공동창업자) – Semantic Versioning 제안
  https://tom.preston-werner.com/
• Martin Fowler – Release practices & Continuous Delivery
  https://martinfowler.com/articles/continuousIntegration.html
• Angular Conventional Commits guideline
  https://github.com/angular/angular/blob/main/CONTRIBUTING.md
• semantic-release 공식 문서
  https://semantic-release.gitbook.io/semantic-release/
• GitHub Release Docs
  https://docs.github.com/en/repositories/releasing-projects-on-github

마무리

릴리즈 관리라는 게 처음엔 꽤 어렵게 느껴지는데, 결국 핵심 흐름은 단순하다.

버전 규칙을 지키고 → 태그로 기록하고 → 자동화로 배포하고 → 언제든 롤백할 수 있게 하는 것

 

이 세 가지만 잡히면 어떤 회사든 배포 프로세스를 이해할 수 있고, 오픈소스도 기여하기 훨씬 쉬워진다.