GitLab 브랜치 전략 및 운영 정책¶

GitLab 프로젝트에서 사용하는 브랜치 전략, 브랜치 보호 정책, Merge Request(MR) 운영 기준, Default Branch 및 rollback 기준을 정의하는 기준 문서임.

1. 개요¶

본 정책은 다음을 보장하기 위해 정의됨:

운영 브랜치 보호
실수로 인한 직접 배포 방지
단계별 검증 흐름 확보
브랜치 난립 방지
MR 기반 변경 관리

2. 브랜치 구조¶

2.1 브랜치 구성¶

브랜치	역할	정책
any work branch	개인 작업 브랜치	작업
develop	개발 통합 브랜치	Maintainers 직접 push/merge 가능, Developers MR 생성
pre-production	검증/스테이징 브랜치	direct push 금지, MR만
production	운영 배포 브랜치 (default)	direct push 금지, MR만

2.2 브랜치 흐름¶

any work branch → develop → pre-production → production

2.3 MR 경로 검증 정책¶

MR pipeline에서는 브랜치 이름 자체를 강제하지 않고, MR의 source/target 경로만 검증함.

작업 브랜치 이름은 목적에 맞게 자유롭게 사용할 수 있으나, 환경 승격 흐름은 반드시 아래 순서를 따라야 함.

허용되는 MR 경로:

any work branch → develop
develop → pre-production
pre-production → production

차단되는 MR 경로 예시:

작업 브랜치 → pre-production
작업 브랜치 → production
develop → production
pre-production → develop
production → develop
production → pre-production

이 검증은 CI pipeline 내 검증 단계(예: mr_sanity_check)에서 수행함.

Pipelines must succeed 설정이 활성화되어 있어야 잘못된 MR 경로가 실제 merge 단계에서 차단됨.

3. Repository 초기 연결 이후 적용 기준¶

Repository 초기 연결, 기존 소스 연결, 최초 commit, production 최초 push, 운영 브랜치 생성은 아래 문서를 기준으로 수행함.

15-GitLab Project 초기 설정 및 Repository 연결 Runbook

본 문서는 Repository 초기 연결이 완료된 이후 적용하는 브랜치 전략, 브랜치 보호 정책, Merge Request 정책, Default Branch 정책을 정의함.

확인 명령:

git fetch origin --prune
git branch -a

로컬 작업 브랜치 기준:

develop

정상 기준:

origin/develop
origin/pre-production
origin/production

Default Branch 는 production 으로 설정함.

4. 개발 브랜치 생성 정책¶

운영 책임자 계정 또는 해당 Project 에 권한을 부여받은 개발자 계정으로 수행함.

4.1 필수 규칙¶

모든 개발 작업은 반드시 develop 브랜치 기준으로 수행함
pre-production, production 에서 브랜치 생성 금지
작업 단위 기준으로 브랜치 생성
브랜치 이름은 작업 목적을 명확히 표현해야 함
권장 브랜치 유형:
- feature/{작업명}
- bugfix/{작업명}
- hotfix/{작업명}
- chore/{작업명}

4.2 브랜치 생성¶

git switch develop
git pull origin develop
git switch --create {작업브랜치명}

git switch {작업브랜치명}

예시:

git switch develop
git pull origin develop
git switch --create bugfix/login-api

git switch bugfix/login-api

작업 브랜치를 원격 Repository 에 생성해야 하는 경우 아래 명령을 수행함.

git add .
git commit -m "{커밋메시지}"
git push --set-upstream origin {작업브랜치명}

예시:

git add .
git commit -m "fix: login api"
git push --set-upstream origin bugfix/login-api

5. 브랜치 정리 정책¶

최고 관리자 계정(Admin) 또는 운영 책임자 계정 으로 수행함.

5.1 필수 규칙¶

작업 완료된 브랜치는 반드시 삭제함
merge된 브랜치는 즉시 삭제함
장기 방치 브랜치 생성 금지

5.2 브랜치 삭제¶

로컬 삭제¶

git branch -d {작업브랜치명}

원격 삭제¶

git push origin --delete {작업브랜치명}

6. 브랜치 보호 정책¶

최고 관리자 계정(Admin) 또는 운영 책임자 계정 으로 수행함.
브랜치 보호 설정을 통해 운영 브랜치의 직접 수정 및 실수 배포를 방지함.
접근 권한 부여 기준은 17-GitLab 접근 제어 정책을 따름.

6.1 경로¶

Project → Settings → Repository → Branch rules

6.2 브랜치별 정책¶

develop¶

Protected: 활성화
Allowed to merge: Maintainers
Allowed to push and merge: Maintainers
Force push: 비활성화

운영 기준:

개발 통합 브랜치
Maintainers 는 develop 브랜치에 직접 push 가능
Maintainers 는 develop 브랜치로 들어오는 MR merge 가능
Developers 는 develop 브랜치에 직접 push 불가
Developers 는 작업 브랜치 생성 및 MR 생성까지만 수행
MR 경로 검증은 CI pipeline 내 검증 단계(예: mr_sanity_check)를 통해 수행

pre-production¶

Protected: 활성화
Allowed to merge: Maintainers
Allowed to push and merge: No one
Force push: 비활성화

운영 기준:

검증/스테이징 브랜치
직접 push 금지
반드시 MR을 통해서만 반영
Maintainers 만 MR merge 가능

production¶

Protected: 활성화
Allowed to merge: Maintainers
Allowed to push and merge: No one
Force push: 비활성화

운영 기준:

운영 배포 브랜치
Project 의 Default Branch 로 사용함
직접 push 금지
반드시 MR을 통해서만 반영
Maintainers 만 MR merge 가능

6.3 운영 메모¶

develop 브랜치는 Maintainers 직접 push 를 허용함. MR pipeline 에서는 any work branch → develop, develop → pre-production, pre-production → production 경로만 성공 처리함. 환경 브랜치 승격 경로 검증은 CI pipeline 내 검증 단계(예: mr_sanity_check)에서 수행함.

7. Merge Request(MR) 정책¶

최고 관리자 계정(Admin) 또는 운영 책임자 계정 으로 수행함.
develop 브랜치는 Maintainer의 직접 push를 허용하되, 일반 작업은 MR 기반으로 수행하는 것을 원칙으로 함.
pre-production, production 브랜치 변경은 반드시 MR을 통해서만 반영해야 함.

7.1 경로¶

Project → Settings → Merge requests

7.2 Merge 조건¶

Merge method: Merge commit
Squash commits when merging: Allow
Pipelines must succeed: 활성화
- 단, CI/CD 설정 파일 자체를 수정하여 기존 pipeline rules가 merge를 차단하는 경우에 한해 일시적으로 비활성화 후 CI 수정사항을 환경 브랜치까지 반영하고 즉시 재활성화함
All threads must be resolved: 활성화

7.3 MR 흐름¶

any work branch → develop: 선택적으로 squash 가능
develop → pre-production: squash 금지
pre-production → production: squash 금지

개발 반영¶

any work branch → develop

검증 반영¶

develop → pre-production

운영 반영¶

pre-production → production

7.4 검증 기준¶

MR 생성 후 변경사항(diff) 확인
pre-production 단계에서 1차 검증
production 단계에서 2차 검증

7.5 운영 메모¶

GitLab Free 플랜 기준 Approval rules 미사용
단계별 MR 검증으로 품질 확보
접근 권한과 프로젝트 멤버 권한 기준은 17-GitLab 권한 제한을 따름

8. Force Push 정책¶

모든 브랜치에서 force push 금지
히스토리 변경 금지
필요 시 revert commit 또는 MR 기반 rollback 사용

9. 금지 사항¶

production 브랜치 직접 push 금지
pre-production 브랜치 직접 push 금지
develop 외 브랜치에서 브랜치 생성 금지
force push 금지
MR 없이 운영 브랜치에 코드 반영 금지

10. Default Branch 정책¶

Default branch는 production으로 설정함
모든 배포 기준은 production 브랜치를 기준으로 함
MR 흐름의 최종 목적지는 production

11. 운영 흐름 요약¶

1. develop 기준으로 브랜치 생성
2. any work branch → develop MR
3. develop → pre-production MR
4. pre-production → production MR
5. 작업 완료 브랜치 즉시 삭제

12. 긴급 대응 및 Hotfix 기준¶

12.1 원칙¶

긴급 상황에서도 pre-production, production 브랜치 직접 push 금지
반드시 MR 기반으로 처리
필요 시 hotfix/* 브랜치를 사용함

12.2 Hotfix 흐름¶

hotfix/* → develop → pre-production → production

13. Rollback 기준¶

운영 장애 발생 시 이전 commit으로 되돌리는 기준은 production 브랜치를 기준으로 함
필요 시 이전 MR 또는 commit 기준으로 rollback 수행
직접 push를 통한 긴급 수정 금지, 반드시 MR 기반으로 처리