[BlerOn] 브랜치 전략
BlerOn 백엔드 브랜치 전략
BlerOn 백엔드에서 사용하는 Git 브랜치 전략을 정리한 문서다.
이 전략의 핵심은 "매주 목요일 정기 배포"라는 고정된 주간 사이클을 중심으로, 각 브랜치의 역할과 머지 흐름을 명확하게 분리하는 데 있다.
여러 명이 동시에 기능을 개발하더라도 아래 세 가지를 항상 구분할 수 있어야 사고를 막을 수 있다.
| 구분 | 브랜치 | 의미 |
|---|---|---|
| 운영 | main |
실제 사용자에게 나가는 코드 |
| 배포 후보 | release |
검수 완료되어 이번 주 배포를 기다리는 코드 |
| 개발·QA | develop |
개발서버에서 통합 테스트·검수 중인 코드 |
그 구분을 브랜치로 강제하는 것이 이 전략의 목적이다.
한눈에 보기
| 항목 | 내용 |
|---|---|
| 배포 주기 | 매주 목요일 정기 배포 |
| Code Freeze | 수요일 오후 — 이후 완료분은 차주로 이월 |
| QA 위치 | develop(개발서버)에서 검수 |
| release 역할 | 검수 완료분만 모아 두는 배포 후보 브랜치 |
| hotfix | main 기준 분기 → main + 차주 release + develop 3곳 동시 머지 |
정상 흐름
feature/bug → develop → release → main
긴급 흐름
main → hotfix → main + release + develop
1. 브랜치 역할
먼저 각 브랜치가 어떤 일을 담당하는지부터 정리한다.
가장 중요한 구분은 "직접 커밋이 가능한 브랜치" 와 "머지(merge)로만 코드가 들어오는 브랜치" 다.
| 브랜치 | 역할 | 직접 커밋 | 자동 배포 |
|---|---|---|---|
main |
운영 배포 전용 | ❌ Only Merge | ✅ 운영서버 |
release/YYYYMMDD |
배포 후보 모음 (검수 완료분) | ❌ Only Merge | — |
develop |
QA · 통합 테스트 | ❌ Only Merge | ✅ 개발서버 |
feature/{이슈번호} |
기능 개발 | ✅ | — |
bug/{이슈번호} |
버그 수정 | ✅ | — |
hotfix/{이슈번호} |
운영 긴급 수정 | ✅ | — |
정리하면
보호 브랜치 — main / release / develop
- 개발자가 직접 코드를 밀어 넣을 수 없다.
- 오직 PR(Pull Request) 머지를 통해서만 코드가 반영된다.
- 검수되지 않은 코드가 운영이나 검수 라인에 섞여 들어가는 사고를 막기 위한 장치다.
작업 브랜치 — feature / bug / hotfix
- 개발자가 실제로 코드를 작성하는 브랜치다.
- 작업이 끝나면 보호 브랜치로 머지하고, 원격 브랜치는 즉시 삭제한다.
QA와 release의 관계
- QA(검수)는
develop(개발서버)에서 수행한다. release는 별도로 배포해서 QA하는 환경이 아니다.develop에서 검수가 완료된 건만 골라 모아 두는 "배포 후보 모음" 브랜치다.- 검증이 끝난 코드가 운영(
main) 직전에 머무는 대기 라인 역할을 한다.
브랜치 이름 규칙
| 브랜치 | 분기 기준 | 용도 |
|---|---|---|
feature/{이슈번호} |
develop |
새 기능 개발 |
bug/{이슈번호} |
develop |
기존 기능 결함 수정 |
hotfix/{이슈번호} |
main |
운영 긴급 수정 |
{이슈번호}에는 Jira/GitHub Issue 등 이슈 트래커의 번호를 넣는다.
예)feature/1234,bug/1287,hotfix/1305
2. 브랜치 흐름도
전체 흐름을 그림으로 보면 다음과 같다.
feature/bug에서 시작한 코드 →develop→release→main(한 방향)- 긴급 상황에서만
hotfix가main에서 분기 → 여러 곳으로 다시 합쳐짐
| 단계 | 흐름 | 설명 |
|---|---|---|
| ① 개발 완료 머지 | feature/bug → develop |
개발서버 자동 배포 후 QA·통합 테스트 수행 |
| ② 검수 완료분 머지 | develop → release |
QA 통과분만 선별. develop에 있다고 무조건 배포되지 않음 |
| ③ 목요일 배포 | release → main |
운영서버 자동 배포 |
| ④ 배포 후 동기화 | main → develop |
두 브랜치의 기준선을 맞춤 |
| hotfix | main → 3곳 머지 |
main + 차주 release + develop에 동시 반영 |
실선 = 메인 흐름의 머지
점선 = 동기화/반영을 위한 보조 머지
3. 주간 배포 사이클
이 전략의 가장 큰 특징은 요일 기반의 고정된 배포 리듬이다.
"언제 코드가 잠기고(Code Freeze), 언제 배포되는지"를 팀 전체가 예측할 수 있게 만든다.
요일별 한눈에 보기
| 월~화 | 수요일 | 수~목 | 목요일 | 목요일(배포 후) |
|---|---|---|---|---|
| 개발 + QA | 검수 완료분 release 머지 Code Freeze |
릴리즈 최종 점검 | 배포 | 차주 준비 |
요일별 상세 작업
| 시점 | 작업 내용 |
|---|---|
| 월 ~ 화 | feature/bug 개발→ develop 머지→ 개발서버에서 QA·통합 테스트 |
| 수요일 | develop에서 QA 검수 완료 항목만 release에 머지Code Freeze — 이후 완료분은 차주 release로 이동 |
| 수 ~ 목 | release(검수 완료분) 최종 점검 후 배포 준비 |
| 목요일 | release → main 머지 → 운영 자동배포 |
| 목요일(배포 후) | 차주 release/YYYYMMDD 생성 (main 기준)main → develop 동기화 머지 |
Code Freeze가 왜 중요한가
처음 Git 브랜치 전략을 접하는 입장에서 가장 낯선 개념이 Code Freeze(코드 동결) 일 수 있다.
| 문제 | 해결 |
|---|---|
| 배포 직전까지 코드를 계속 추가하면 | QA가 검증한 코드 ≠ 실제 배포 코드 |
수요일 오후 이후 release 머지 금지 |
이번 주 배포 대상을 확정 |
| 동결 이후 완료된 작업 | 차주 release로 이월 (hotfix 제외) |
한 줄 요약
"이번 주에 나갈 코드는 수요일에 확정하고, 목요일까지는 그 확정된 코드만 검증·배포한다."
4. 상세 절차
실제로 브랜치를 어떻게 만들고 머지하는지 시나리오별로 정리한다.
4-1. 기능 개발 (feature)
| 순서 | 작업 |
|---|---|
| 1 | develop 기준으로 feature/{이슈번호} 브랜치 생성 |
| 2 | 개발 완료 → develop 머지 (PR) → 개발서버 QA·통합 테스트 |
| 3 | QA 검수 완료 → release 머지 (PR 코드 리뷰 필수) |
| 4 | 원격 feature 브랜치 즉시 삭제 |
# 1. develop 기준으로 feature 브랜치 생성
git checkout develop
git pull origin develop
git checkout -b feature/1234
# 2. 개발 후 develop으로 머지 (PR) → 개발서버 QA·통합 테스트
# GitHub/GitLab: feature/1234 → develop PR 생성
# 3. QA 검수 완료 → release 브랜치로 머지 (PR 코드 리뷰 필수)
# feature/1234 → release/YYYYMMDD PR 생성
# 4. 머지 완료 후 원격 feature 브랜치 즉시 삭제
git push origin --delete feature/1234
⚠️ 테스트 실패 시
develop에서 해당 커밋을revert한 뒤 재개발한다.
develop은 보호 브랜치이므로 강제 푸시로 이력을 지우지 않는다.
4-2. 버그 수정 (bug)
| 순서 | 작업 |
|---|---|
| 1 | develop 기준으로 bug/{이슈번호} 브랜치 생성 |
| 2 | 수정 완료 → develop 머지 → 개발서버 QA 검수 |
| 3 | QA 검수 완료 → release 머지 |
| 4 | 원격 bug 브랜치 즉시 삭제 |
feature와 절차는 동일하다. 기존 기능의 결함을 고치는 작업이라는 점만 다르다.
⚠️
release머지 전 PR 코드 리뷰 필수 — develop의 미검수 코드가 release에 혼입되는 것을 방지한다.
4-3. 긴급 운영 수정 (hotfix)
| 순서 | 작업 |
|---|---|
| 1 | main 기준으로 hotfix/{이슈번호} 브랜치 생성 |
| 2 | 수정 완료 → main + release(차주) + develop 3곳 동시 머지 |
| 3 | 원격 hotfix 브랜치 즉시 삭제 |
# 1. main 기준으로 hotfix 브랜치 생성
git checkout main
git pull origin main
git checkout -b hotfix/1305
# 2. 수정 후 main + 차주 release + develop 3곳에 동시 머지
# (각각 PR 생성)
# 3. 원격 hotfix 브랜치 즉시 삭제
git push origin --delete hotfix/1305
⚠️ develop 동기화 누락 시 다음 배포에서 동일 버그가 재발한다.
hotfix는main에서 분기했기 때문에, develop/release에 반영하지 않으면
다음 주 정기 배포 때 "고치기 전 코드"가 다시 운영으로 나간다.
5. 핵심 원칙
| # | 원칙 | 내용 |
|---|---|---|
| 1 | QA는 develop에서 | 검수는 develop(개발서버)에서 수행 |
| 2 | release는 검수 완료분 모음 | 직접 커밋 금지, PR을 통해서만 반영 |
| 3 | Code Freeze | 수요일 오후 이후 release 머지 금지 |
| 4 | hotfix 3곳 동시 머지 | main + release(차주) + develop 필수 |
| 5 | 원격 브랜치 즉시 삭제 | feature/bug/hotfix 머지 후 원격 삭제 |
| 6 | PR 코드 리뷰 필수 | develop → release 머지 전 반드시 리뷰 |
6. staging 환경에 대한 고민과 현실적 선택
브랜치 전략을 설계하면서 가장 아쉬웠던 부분은 별도의 staging(스테이징) 환경을 두지 못했다는 점이다.
이 절은 "왜 staging이 없는지, 그래서 어떻게 대응하는지"를 솔직하게 기록한다.
6-1. 환경 구성 현황
현재 BLER 서비스는 두 개의 환경으로만 운영된다.
| 환경 | 대응 브랜치 | 용도 |
|---|---|---|
| 개발(Development) | develop |
QA·통합 테스트, 검수 수행 |
| 운영(Production) | main |
실제 사용자 서비스 |
- QA·검수는 모두 개발서버(
develop)에서 수행한다. - 검수가 완료된 건만
release에 모아 배포 후보로 확정한다.
다만 이상적으로는 운영 배포 직전에 운영과 거의 동일한 환경에서 최종 검증하는 staging 환경이 한 단계 더 있는 것이 좋다.
develop(개발서버)은 데이터와 설정이 운영과 다르기 때문에, 개발서버 QA에서 잘 되던 기능이 운영에서는 데이터 차이로 문제를 일으키는 경우가 있다.
6-2. 원래 의도했던 staging 구성
| 항목 | 계획 |
|---|---|
| DB | 전일(D-1) 운영 데이터를 매일 백업 → staging DB로 복원 |
| 환경 | 운영과 동일한 수준의 데이터·설정 |
| 배포 | release 브랜치를 staging에 배포 → 실데이터에 가까운 조건에서 최종 검증 |
평소 QA는 개발서버(develop)에서 하되, 배포 후보가 모인 release만큼은 운영과 동일한 데이터 환경에서 다시 한번 확인하려는 것이 목표였다.
6-3. 현실적 제약 — 미지원
| 제약 | 내용 |
|---|---|
| 서버 | 별도 staging 서버(애플리케이션 + DB)를 띄울 인프라 자원 없음 |
| 스토리지 | 전일 운영 DB daily 백업·복원 파이프라인 운영 비용 미지원 |
결과적으로 staging 환경 없이 개발(develop) → 운영(main) 2단계 구조로 운영하고 있다.
6-4. staging 부재를 보완하는 장치
| # | 보완 장치 | 설명 |
|---|---|---|
| 1 | develop QA를 1차 방어선 | 검수 완료분만 release로 모아 배포 후보 확정 |
| 2 | Code Freeze | 검수한 코드 = 배포할 코드 등식 보장 |
| 3 | PR 코드 리뷰 필수화 | 실데이터 검증 환경 없는 만큼 사람이 보는 리뷰 비중 확대 |
| 4 | hotfix 프로세스 정비 | 운영 이슈 빠른 수습을 위해 3곳 동시 머지 규칙 명확화 |
6-5. 향후 개선 방향
리소스가 확보되면 다음 순서로 staging 환경을 도입하는 것이 목표다.
| 단계 | 내용 |
|---|---|
| 1단계 | 운영 DB 전일 백업 → staging DB 복원 daily 파이프라인 구축 |
| 2단계 | release 브랜치 전용 staging 애플리케이션 서버 분리 배포 |
| 3단계 | staging 검증 통과를 main 머지의 필수 게이트(gate)로 승격 |
정리
staging 환경은 기술적 필요성을 인지하고 설계까지 마쳤으나,
사내 추가 서버 리소스 미지원으로 보류된 상태다.
현재는developQA +release검수 완료분 모음 + Code Freeze + 코드 리뷰로 그 공백을 메우고 있다.
마무리
이 브랜치 전략의 본질은 화려한 도구가 아니라 "역할 분리 + 고정된 리듬 + 명확한 약속" 이다.
| 요소 | 내용 |
|---|---|
| 역할 분리 | 보호 브랜치(main/release/develop) vs 작업 브랜치(feature/bug/hotfix) |
| 고정된 리듬 | 매주 목요일 배포 + 수요일 Code Freeze |
| 명확한 약속 | PR 코드 리뷰, hotfix 3곳 동시 머지 |
staging 환경처럼 갖추지 못한 부분은 분명히 있지만, 그 한계를 인지하고 프로세스로 보완한다는 점에서 이 전략은 "현재 가진 리소스 안에서의 최선" 이라 할 수 있다.