[ CI/CD ] 모노레포 Gitlab CI/CD 전략

모노레포 CI/CD 배포 전략

모노레포 환경에서 release 브랜치 기반의 자동화된 배포 파이프라인을 구축한 경험을 공유합니다. 버전 검증부터 NPM 배포까지 전 과정을 CI가 자동으로 처리하도록 설계했습니다.

🚀 배포 흐름 개요

전체 흐름도

develop에서 release 브랜치를 생성하고 QA를 거쳐 main에 병합되면 자동으로 버전 범핑과 NPM 배포가 이루어집니다.

배포 파이프라인 전체 흐름

개발

develop

QA

release/v1.0.0

개발 서버

CI: 버전 검증

Production

main

Production

CI: auto-release

CI: publish

develop

→ branch →

release/*

→ PR & Merge →

main

→ 버전 범핑 & 태그 → NPM 배포

자동화된 릴리즈 흐름

단계	작업	시점	담당
2	브랜치 버전 검증	release/* 브랜치 push 시	CI 자동
3	QA 진행	release 브랜치에서	수동
4	main 병합	QA 완료 후	수동 (PR Merge)
5	버전 범핑	release/* → main 병합 시	CI 자동
6	태그 생성	release/* → main 병합 시	CI 자동
7	패키지 배포	태그 push 시	CI 자동

---

⚙️ CI/CD 파이프라인 구조

파이프라인 다이어그램

CI/CD 파이프라인 스테이지

install

→

build

→

test / lint

→

validate

→

release

→

publish

↳ validate 단계는 release/* 브랜치에서만 버전 검증 실행

Stage별 Job 설명

Stage	Job	트리거 조건	역할
install	install	모든 브랜치/태그	의존성 설치 (pnpm install)
build	build	모든 브랜치/태그	패키지 빌드
test	lint	feature/*, develop, release/*, main	ESLint 검사
test	test	feature/*, develop, release/*, main	테스트 실행
validate	validate-release-branch	release/v* 브랜치	버전 형식 및 유효성 검증
release	auto-release	main 브랜치 (merge 시)	버전 범핑 및 태그 생성
publish	publish	v* 태그	NPM 레지스트리 배포

---

🔍 Release 브랜치 버전 검증

release 브랜치가 push되면 CI가 자동으로 버전의 유효성을 검증합니다.

검증 항목

1

형식 검증

브랜치 이름이 release/v<Major>.<Minor>.<Patch> 형식인지 확인합니다.

2

버전 비교

새 버전이 기존 태그보다 높은지 확인합니다.

검증 결과 예시

# ✅ 통과 예시
기존 최신 태그: v1.0.0
새 브랜치: release/v1.1.0  # 통과: 1.1.0 > 1.0.0

기존 최신 태그: v2.3.1
새 브랜치: release/v2.3.2  # 통과: 2.3.2 > 2.3.1

# ❌ 실패 예시
release/version-1.0.0  # 형식 오류 (v가 없음)
release/v0.9.0         # 기존 v1.0.0보다 낮음
release/v1.0.0         # 이미 존재하는 태그

검증 실패 시

CI 파이프라인이 실패하며 release 브랜치 이름을 올바른 형식으로 수정해야 합니다.

# 잘못된 브랜치 삭제 후 올바른 이름으로 재생성
git branch -d release/wrong-name
git checkout -b release/v1.2.0

---

자동 릴리즈 프로세스

트리거 조건

• main 브랜치에 push (merge commit)
• Merge 메시지에 release/v<version> 패턴이 포함된 경우

자동 처리 흐름

Auto Release 시퀀스

release/v1.2.0

main

CI (auto-release)

Git Tag

NPM Registry

1

release → main Merge
release/v1.2.0 브랜치가 main에 병합됩니다.

2

CI 트리거
main 브랜치 push 이벤트로 auto-release job이 시작됩니다.

3

버전 추출
Merge commit 메시지에서 버전 정보(v1.2.0)를 추출합니다.

4

Changeset 처리 및 버전 범핑
pnpm changeset:auto → pnpm version-packages

5

Git Tag 생성
git tag v1.2.0을 생성하고 push합니다.

6

NPM 배포
태그 push 이벤트로 publish job이 실행되어 NPM 레지스트리에 배포됩니다.

자동 처리 내용

단계	명령어	설명
버전 추출	-	Merge commit 메시지에서 버전 정보 추출
Changeset 생성	pnpm changeset:auto	Changeset 파일 자동 생성
버전 범핑	pnpm version-packages	package.json 버전 업데이트
태그 생성	git tag v1.2.0	Git 태그 생성 및 Push
패키지 배포	pnpm publish	NPM 레지스트리 배포

---

버전 관리 (Semantic Versioning)

버전 형식

Semantic Versioning 구조

v1.2.3

Major: 1

Breaking Change
호환성이 깨지는 변경

Minor: 2

새 기능 추가
(하위 호환 유지)

Patch: 3

버그 수정
리팩터링 등

Commit Type → Version 매핑

Commit Type	Version Bump	설명
feat	Minor	새 기능 추가
improve	Minor	기존 기능 개선
fix	Patch	버그 수정
perf	Patch	성능 개선
refactor	Patch	코드 리팩토링
feat! / BREAKING CHANGE	Major	호환성이 깨지는 변경
docs, test, chore, style, ci	-	버전 영향 없음

---

Changeset 사용법

Changeset이란?

Changeset은 모노레포에서 패키지 버전 관리를 자동화하는 도구입니다. 변경된 패키지만 버전이 업데이트되고 의존성 있는 패키지도 자동으로 처리됩니다.

사용 방법

# 1. 대화형 changeset 생성
pnpm changeset
# → 변경된 패키지 선택 → 버전 타입 선택 → 변경 내용 요약 작성

# 2. 자동 changeset 생성 (마지막 릴리즈 이후 커밋 분석)
pnpm changeset:auto

# 3. 버전 업데이트 적용
pnpm version-packages

Changeset 파일 예시

.changeset/brave-lions-dance.md 파일 형태로 생성됩니다.

---
"@workspace/core": minor
"@workspace/hooks": patch
---

feat: 새로운 Button 컴포넌트 추가
fix: useDebounce 훅 메모리 누수 수정

⚠️ 주의

pnpm version-packages 실행 시 changeset 파일이 소비되고 삭제됩니다.