GitLab Repository Restore & Local Workspace Connection Guide¶

0. 전제¶

기존 GitLab 저장소를 mirror 백업 기준으로 신규 GitLab 프로젝트에 복구하고, 로컬 개발 환경을 신규 GitLab 저장소에 연결하는 절차를 정의함.

대상:

기존 GitLab repository mirror 백업
신규 GitLab project
로컬 개발 환경
VSCode 기반 Git workspace

운영 기준:

신규 GitLab 프로젝트는 empty repository 로 생성함
기존 mirror 백업을 기준으로 모든 branch 및 commit history 를 복구함
main 은 백업/보관용 branch 로 유지함
실제 개발 및 배포 흐름은 develop → pre-production → production 기준으로 운영함
모든 운영 branch 변경은 Merge Request 기준으로 수행함

1. 신규 GitLab Project 생성¶

GitLab UI 에서 신규 project 를 생성함.

경로:

GitLab → Group → Project 생성

설정:

Visibility: Private
Initialize repository with README: 비활성화
Project type: Empty repository

주의:

README 자동 생성 옵션을 활성화하지 않음
초기 commit 이 생성되면 mirror push 시 충돌 가능성이 있음
신규 project 는 empty repository 상태로 생성함

2. 기존 Repository Mirror 복구¶

기존 mirror 백업 repository 를 기준으로 신규 GitLab project 에 복구함.

전제:

기존 mirror backup repository 존재
예: client2.git

복구 명령:

git clone --mirror <기존_백업_repo>
cd <repo>.git

git remote set-url origin https://gitlab.example.com/example/frontend/example.com.git
git push --mirror

결과:

기존 commit history 가 복구됨
기존 branch 가 복구됨
tag 가 있는 경우 함께 복구됨
일부 hidden refs 는 reject 될 수 있음

참고:

refs/merge-requests/*
refs/pipelines/*
refs/environments/*

위와 같은 hidden refs 는 GitLab 내부 참조이므로 push reject 가 발생할 수 있음.
일반 branch, tag, commit history 가 정상 복구되면 무시 가능함.

3. 불필요 Branch 정리¶

복구 후 기존 프로젝트에서 사용하던 테스트 branch 또는 이력 branch 를 정리함.

GitLab UI 경로:

Project → Code → Branches

정리 기준:

운영에 사용하지 않는 branch 삭제
테스트용 branch 삭제
이전 프로젝트 이력성 branch 삭제
main 은 백업/보관용으로 유지함

초기 정리 후 유지 branch:

main

주의:

main 은 이후 운영 branch 기준이 아니라 백업/보관용으로만 사용함
실제 개발 및 배포 branch 는 별도로 생성함

4. 운영 Branch 생성¶

main 기준으로 운영 branch 를 생성함.

생성 branch:

develop
pre-production
production

브랜치 역할:

Branch	역할
`develop`	개발 통합 branch
`pre-production`	사전 운영 검증 branch
`production`	운영 배포 기준 branch
`main`	백업/보관용 branch

운영 기준:

feature/* branch 는 develop 기준으로 생성함
pre-production 은 운영 전 검증 기준으로 사용함
production 은 실제 운영 배포 기준으로 사용함
main 은 직접 사용하지 않음

5. Branch 보호 정책 설정¶

GitLab Branch rules 에서 branch 보호 정책을 설정함.

GitLab UI 경로:

Project → Settings → Repository → Branch rules

정책:

Branch	Push	Merge
`develop`	Maintainers	Maintainers
`pre-production`	No one	Maintainers
`production`	No one	Maintainers
`main`	No one	No one

운영 기준:

develop 은 Maintainer 만 직접 push 가능함
pre-production 은 직접 push 금지함
production 은 직접 push 금지함
main 은 push / merge 모두 금지함
운영 branch 변경은 Merge Request 기준으로 수행함

목적:

운영 branch 직접 수정 차단
Merge Request 기반 변경 이력 확보
production branch 보호
main branch 를 백업/보관용으로 고정

6. Default Branch 변경¶

GitLab project 의 default branch 를 production 으로 변경함.

GitLab UI 경로:

Project → Settings → Repository

설정:

Default branch: production

운영 기준:

신규 GitLab project 의 기본 branch 는 production 으로 설정함
로컬 Git 의 origin/HEAD 도 이후 origin/production 으로 동기화함

7. 로컬 개발 환경 Remote 변경¶

기존 로컬 프로젝트가 이전 GitLab repository 를 바라보고 있으므로 remote URL 을 신규 GitLab project 로 변경함.

기존 remote 확인:

git remote -v

신규 GitLab remote 로 변경:

git remote set-url origin https://gitlab.example.com/example/frontend/example.com.git

변경 확인:

git remote -v

원격 branch 동기화:

git fetch origin

운영 기준:

로컬 repository 는 신규 GitLab project 를 origin 으로 바라보아야 함
remote 변경 후 반드시 git fetch origin 으로 원격 branch 정보를 갱신함

8. 로컬 Branch 정리¶

기존 프로젝트 기준으로 남아 있는 로컬 branch 및 원격 추적 branch 캐시를 정리함.

원격 추적 branch 정리:

git fetch origin --prune

원격 branch 확인:

git branch -r

정상 상태:

origin/HEAD -> origin/production
origin/develop
origin/pre-production
origin/production
origin/main

로컬 branch 확인:

git branch

불필요 로컬 branch 삭제:

git branch -D <브랜치명>

develop branch 로 전환:

git checkout develop

로컬에 develop branch 가 없는 경우:

git checkout -b develop origin/develop

운영 기준:

로컬 작업 기준 branch 는 develop 임
기존 프로젝트에서 사용하던 불필요 로컬 branch 는 삭제함
원격 branch 목록은 git fetch origin --prune 으로 정리함

9. Default Branch 로컬 동기화¶

GitLab default branch 변경 사항을 로컬 Git 에 반영함.

git remote set-head origin -a

확인:

git branch -r

정상 상태:

origin/HEAD -> origin/production

주의:

GitLab default branch 가 production 으로 변경된 뒤 실행함
로컬 origin/HEAD 가 origin/production 을 가리켜야 함

10. 최종 상태¶

복구 및 로컬 연결 완료 후 최종 상태는 아래와 같음.

로컬 branch:

develop

원격 branch:

develop
pre-production
production
main

default branch:

production

branch 역할:

Branch	상태
`develop`	로컬 개발 기준
`pre-production`	사전 운영 검증 기준
`production`	운영 배포 기준 / default branch
`main`	백업/보관용

11. 이후 작업 방식¶

feature branch 는 develop 기준으로 생성함.

git checkout develop
git pull origin develop
git checkout -b feature/{작업명}

작업 완료 후 원격에 push 함.

git push -u origin feature/{작업명}

Merge Request 흐름:

feature → develop → pre-production → production

운영 기준:

feature 작업은 반드시 develop 기준으로 시작함
pre-production, production 직접 push 금지함
운영 반영은 Merge Request 기준으로 수행함
작업 완료 후 feature branch 는 merge 이후 삭제 가능함

12. 주의 사항¶

main branch 는 사용하지 않음
main branch 는 백업/보관용으로 유지함
production branch 는 직접 push 하지 않음
pre-production branch 는 직접 push 하지 않음
모든 운영 변경은 Merge Request 기준으로 수행함
mirror push 이후 hidden refs reject 는 일반 branch 복구와 별개로 판단함
신규 GitLab project 생성 시 README 를 생성하지 않음
로컬 remote 변경 후 반드시 원격 branch 를 prune 함

13. 결론¶

본 절차를 통해 기존 GitLab repository 를 신규 GitLab project 로 복구하고, 로컬 개발 환경을 신규 GitLab 기준으로 연결함.

확보되는 결과:

기존 Git commit history 복구
운영 branch 구조 정리
branch protection 정책 적용
default branch 를 production 으로 설정
로컬 개발 환경을 신규 GitLab project 에 연결
feature → develop → pre-production → production 기반 Merge Request 흐름 확보

본 문서 완료 후 신규 GitLab project 는 개발, 검증, 운영 배포 흐름을 위한 기본 branch 구조를 갖춘 상태가 됨.