콘텐츠로 이동

GitLab Project 초기 설정 및 Repository 연결 Runbook

0. 필수 참조

반드시 아래 문서를 기반으로 수행해야 함:


1. 전제 조건

아래 작업이 완료되어 있어야 함.

대상 Repository 기준은 12-GitLab 프로젝트 구조 정책을 따름.

{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}

Repository HTTPS URL 예시:

https://gitlab.example.com/{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}.git

1.1 수행 계정 기준

  • 로컬 Repository 연결, 최초 commit, 운영 브랜치 push 작업은 운영 책임자 계정 기준으로 수행함.
  • 최고 관리자 계정(Admin) 은 Default Branch 변경 또는 Branch rules 설정 중 운영 책임자 계정의 권한이 부족한 경우에만 사용함.

2. GitLab 빈 Repository 화면 기준

서비스 Project Repository 생성 직후 Repository 가 비어 있으면 GitLab 화면에 아래 안내가 표시됨.

The repository for this project is empty

해당 GitLab 화면의 명령을 기준으로 수행함.


3. Repository 연결 방식 선택 기준

로컬 프로젝트 폴더의 상태에 따라 아래 방식 중 하나를 선택함.

구분 로컬 폴더 상태 사용 목적 GitLab 화면 기준
방식 A 빈 프로젝트 폴더가 있고 아직 Git Repository 가 아님 새 GitLab Repository 로 최초 초기화 Create a new repository
방식 B 서비스 소스가 존재하지만 Git Repository 가 아님 기존 서비스 소스를 새 GitLab Repository 에 최초 연결 Push an existing folder
방식 C 이미 Git Repository 로 관리되고 있고 기존 origin 이 존재함 기존 Git Repository 기록을 보존하여 새 GitLab Repository 로 연결 Push an existing Git repository
방식 D 이미 Git Repository 로 관리되고 있으나 기존 기록을 폐기해야 함 현재 파일 상태만 새 GitLab Repository 에 최초 commit 으로 연결 Push an existing folder 변형

각 방식의 실행 절차는 방식 A, 방식 B, 방식 C, 방식 D에 따라 수행함.

3.1 방식 A - 빈 프로젝트 폴더를 새 GitLab Repository 로 초기화

  • VS Code 작업 위치는 {PROJECT_NAME}/{SERVICE_PREFIX}
  • 빈 프로젝트 폴더에서 README.md 기준 최초 commit 을 생성하고, 현재 생성한 GitLab Repository 로 push
{PROJECT_NAME}/{SERVICE_PREFIX} 작업 위치가 존재함
{SERVICE_NAME} 폴더는 아직 없거나 새로 생성 가능한 상태임
서비스 소스는 아직 없음
GitLab Repository 는 비어 있음

3.2 방식 B - Git Repository 가 아닌 기존 서비스 소스 폴더를 새 GitLab Repository 에 최초 연결

  • VS Code 작업 위치는 {PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}
  • 기존 서비스 소스 폴더를 Git Repository 로 초기화한 뒤, 현재 생성한 GitLab Repository 를 origin 으로 등록하고 최초 push 하는 절차임.
{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME} 폴더가 이미 존재함
서비스 중인 소스가 폴더 안에 존재함
.git 디렉터리가 없음
GitLab Repository 는 비어 있음

3.3 방식 C - 기존 Git Repository 를 새 GitLab Repository 에 연결

  • VS Code 작업 위치는 {PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}
  • 이미 Git Repository 로 관리 중인 로컬 프로젝트 폴더를 현재 생성한 새 GitLab Repository 에 연결하는 절차임.
  • 기존 commit history, branch, tag 기록을 새 GitLab Repository 로 이전해야 하는 경우 사용함.
  • 기존 origin 은 접속 가능 여부와 무관하게 로컬에 남아 있는 remote 설정임.
  • 기존 remote 기록 보존이 필요하면 old-origin 으로 이름을 변경함.
  • 기존 remote 기록 보존이 필요 없으면 현재 생성한 GitLab Repository 로 origin URL 을 변경함.
{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME} 폴더가 이미 존재함
이미 Git Repository 로 관리되고 있음
기존 origin remote 가 존재함
기존 commit history 를 보존해야 함
현재 생성한 GitLab Repository 로 연결해야 함

복구 기준:

3.4 방식 D - 기존 Git 기록을 폐기하고 새 GitLab Repository 에 최초 연결

  • VS Code 작업 위치는 {PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}
  • 이미 Git Repository 로 관리 중인 로컬 프로젝트 폴더에서 기존 Git 기록을 폐기하고, 현재 파일 상태만 새 GitLab Repository 의 최초 commit 으로 등록하는 절차임.
  • 기존 commit history, branch, tag, remote 기록을 새 GitLab Repository 로 이전하지 않음.
  • 기존 기록을 보존해야 하는 경우에는 방식 D 를 사용하지 않고 방식 C를 사용함.
  • 방식 D 는 기존 .git 디렉터리를 백업하거나 제거한 뒤 방식 B와 동일한 형태로 새 Git Repository 를 초기화하는 절차임.
{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME} 폴더가 이미 존재함
이미 Git Repository 로 관리되고 있음
기존 origin remote 가 존재함
기존 commit history 를 보존하지 않음
현재 파일 상태만 새 GitLab Repository 의 최초 상태로 등록해야 함
GitLab Repository 는 비어 있음

주의:

  • 방식 D 는 기존 Git 기록을 폐기하는 파괴적 절차임
  • 기존 commit history, branch, tag, remote 기록은 새 GitLab Repository 로 이전되지 않음
  • 기존 변경 이력 추적이 필요한 경우 방식 D 를 사용하면 안 됨
  • 기존 기록을 보존해야 하는 경우에는 방식 C 를 사용해야 함

4. Git identity local 설정

  • Git identity 는 개인 PC 전체에 적용되는 global 설정을 사용하지 않고 Project local 설정을 사용함.
  • Git identity 설정 명령은 각 방식의 실행 절차 안에서 수행함.
  • 방식 A 는 git clone{SERVICE_NAME} 디렉터리로 이동한 직후 설정함.
  • 방식 B 는 git init --initial-branch=production --object-format=sha1 직후 설정함.
  • 방식 C 는 새 GitLab Repository 를 origin 으로 연결하기 전 7.4 새 GitLab Repository 를 origin 으로 연결 절차에서 설정함.
  • 방식 D 는 기존 .git 디렉터리 백업 또는 제거 후 방식 B 절차를 수행하면서 git init 직후 설정함.

5. 방식 A - 빈 프로젝트 폴더를 새 GitLab Repository 로 초기화

  • GitLab 빈 Repository 화면의 Create a new repository 안내를 기준으로 수행함.
  • 빈 Repository clone 직후에는 commit 이 없는 상태이므로, 최초 commit 생성 후 local branch 이름을 production 으로 변경함.
  • 최종 Default Branch 기준은 16-GitLab 브랜치 전략 및 운영 정책을 따름.

작업 위치:

{PROJECT_NAME}/{SERVICE_PREFIX}
git clone https://gitlab.example.com/{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}.git
cd {SERVICE_NAME}

# 확인
git config --local --get user.name
git config --local --get user.email

# 설정
git config --local user.name "{MAINTAINER_NAME}"
git config --local user.email "{MAINTAINER_EMAIL}"

macOS / Linux:

touch README.md

Windows VS Code PowerShell:

New-Item -ItemType File -Path README.md
git add README.md
git commit -m "chore: initial commit"

git branch -m production
git push --set-upstream origin production

production 브랜치 최초 push 가 완료되면 후속 절차로 9. 운영 브랜치 생성을 수행함.


6. 방식 B - GitLab 에 연결되지 않은 기존 서비스 소스 폴더를 새 GitLab Repository 에 최초 연결

  • GitLab 빈 Repository 화면의 Push an existing folder 안내를 기준으로 수행함.
  • 기존 서비스 소스 폴더를 Git Repository 로 초기화한 뒤, 현재 생성한 GitLab Repository 를 origin 으로 등록함.
  • 환경 파일, 인증 파일, 빌드 산출물, 로그 파일은 Repository 에 포함하지 않음.
  • 필요 시 git add . 전에 .gitignore 를 먼저 작성함.

작업 위치:

{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}
git init --initial-branch=production --object-format=sha1

# 확인
git config --local --get user.name
git config --local --get user.email

# 설정
git config --local user.name "{MAINTAINER_NAME}"
git config --local user.email "{MAINTAINER_EMAIL}"

git remote add origin https://gitlab.example.com/{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}.git

6.1 .gitignore 작성 및 제외 대상 확인

git add . 실행 전 .gitignore 파일을 작성하거나 기존 내용을 확인함.

.gitignore 파일이 없는 경우 먼저 생성함.

macOS / Linux:

touch .gitignore

Windows VS Code PowerShell:

New-Item -ItemType File -Path .gitignore

.gitignore 파일을 열어 제외 대상을 작성하거나 기존 내용을 확인함.

code .gitignore

주의:

  • 아래와 같은 환경 파일, 인증 파일, 빌드 산출물, 로그 파일 등은 Repository 에 포함하지 않음.

공통:

# 환경/인증
.env
.env.*
*.pem
*.key
*.p12
*.pfx
secrets/
credentials/

# 에디터/OS
.DS_Store
Thumbs.db
.vscode/
.idea/
*.swp
*.swo

C++:

# 빌드 산출물
*.o
*.obj
*.a
*.so
*.so.*
*.dylib
*.dll
*.exe
*.out
build/
dist/
cmake-build-*/
CMakeFiles/
CMakeCache.txt
Makefile

# 디버그
*.dSYM/
*.pdb
core

PHP:

vendor/
# composer.lock 포함 여부는 팀 운영 기준으로 결정
composer.lock
*.log

Laravel & Lumen:

# PHP 포함
vendor/
node_modules/
public/hot
public/storage
storage/*.key
storage/logs/
storage/framework/cache/
storage/framework/sessions/
storage/framework/views/
bootstrap/cache/
.phpunit.result.cache
_ide_helper.php
_ide_helper_models.php
.phpstorm.meta.php

NodeJS (공통):

node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.npm
.yarn/cache
.pnpm-store/
logs/
*.log
pids/
*.pid

NodeJS + Express:

# NodeJS (공통) 포함
dist/
build/
uploads/ # 서비스 업로드 파일 (경로가 다르면 수정)
tmp/

Next.js:

.next/
out/
dist/
build/
.turbo/
.vercel/

Nuxt.js:

.nuxt/
.output/
dist/
.nitro/
.cache/

6.2 git add 전 상태 확인

git add . 실행 전 제외 대상이 정상 반영되었는지 확인함.

git status --short

무시된 파일까지 함께 확인해야 하는 경우 아래 명령을 사용함.

git status --short --ignored

6.3 최초 commit 및 production push

제외 대상 확인이 완료되면 최초 commit 을 생성하고 production 브랜치를 새 GitLab Repository 로 push 함.

git add .
git status
git commit -m "chore: initial commit"
git push --set-upstream origin production

production 브랜치 최초 push 가 완료되면 후속 절차로 9. 운영 브랜치 생성을 수행함.


7. 방식 C - 기존 Git Repository 를 새 GitLab Repository 로 연결

  • GitLab 빈 Repository 화면의 Push an existing Git repository 안내를 기준으로 수행함.
  • 이미 Git Repository 로 관리 중인 로컬 프로젝트 폴더를 현재 생성한 새 GitLab Repository 에 연결함.
  • 기존 GitLab 서버 장애, mirror 백업 복구, branch/history 전체 복원, 로컬 workspace 재연결이 필요한 경우에는 27-GitLab Repository 복구 및 로컬 Workspace 연결 가이드 를 기준으로 수행함.

주의:

  • 기존 Repository 의 branch 구조가 16-GitLab 브랜치 전략 및 운영 정책과 다를 수 있음
  • 새 GitLab Repository 로 push 하기 전에 로컬에서 develop, pre-production, production 브랜치 구조를 먼저 확인함
  • 운영 브랜치가 없는 경우 새 origin 연결 및 push 전에 로컬에서 먼저 운영 브랜치 구조를 정립함
  • 운영 브랜치 생성 전 기존 branch 를 임의로 삭제하지 않음
  • 불필요 branch 삭제는 10. Default Branch 확인 이후 11. 방식 C 불필요 브랜치 정리에서 수행함
  • 로컬에 불필요한 이전 작업 branch, 테스트 branch, 백업 branch 가 많은 경우 --all push 전에 로컬 branch 를 먼저 정리하거나 필요한 branch 만 명시적으로 push 함

작업 위치:

{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}

7.1 로컬 branch 상태 확인

기존 Git Repository 의 현재 branch 상태를 확인함.

git status
git branch
git branch -r

필수 유지 브랜치:

develop
pre-production
production

7.2 운영 브랜치가 이미 존재하는 경우

로컬 Git Repository 에 아래 브랜치가 이미 존재하면 운영 브랜치 생성 절차를 생략함.

develop
pre-production
production

이 경우 7.4 새 GitLab Repository 를 origin 으로 연결 절차로 이동함.

7.3 production 브랜치가 없는 경우

production 브랜치가 없는 경우에는 유지할 기준 branch 를 먼저 결정함.

기준 branch 예시:

main
master
기존 운영 branch

기준 branch 를 선택한 뒤, 기존 원격지의 최신 commit 을 로컬에 반영하고 해당 branch 기준으로 로컬에서 production, pre-production, develop 브랜치를 생성함.

git switch {BASE_BRANCH}
git pull origin {BASE_BRANCH}

git switch --create production

git switch production
git switch --create pre-production

git switch production
git switch --create develop

git switch develop

예시: 기존 master 를 기준으로 운영 브랜치를 생성하는 경우

git switch master
git pull origin master

git switch --create production

git switch production
git switch --create pre-production

git switch production
git switch --create develop

git switch develop

예시: 기존 main 을 기준으로 운영 브랜치를 생성하는 경우

git switch main
git pull origin main

git switch --create production

git switch production
git switch --create pre-production

git switch production
git switch --create develop

git switch develop

주의:

  • 본 절차는 새 GitLab Repository 로 push 하기 전 로컬에서만 수행함
  • 기준 branch 전환 후 기존 원격지에서 git pull origin {BASE_BRANCH} 를 수행하여 최신 commit 을 로컬에 반영함
  • 이 시점의 origin 은 아직 기존 원격지이므로 pull 대상이 새 GitLab Repository 가 아님에 주의함
  • 새 GitLab Repository 를 origin 으로 연결한 뒤에는 기존 원격지 기준 pull 을 수행하지 않음
  • 기준 branch 를 확정하기 전 기존 branch 를 임의로 삭제하지 않음

7.4 새 GitLab Repository 를 origin 으로 연결

7.4.1 기존 origin 기록을 보존하는 경우

기존 origin 기록 보존이 필요한 경우에는 old-origin 으로 이름을 변경함.

# 확인
git config --local --get user.name
git config --local --get user.email

# 설정
git config --local user.name "{MAINTAINER_NAME}"
git config --local user.email "{MAINTAINER_EMAIL}"

git remote rename origin old-origin
git remote add origin https://gitlab.example.com/{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}.git

7.4.2 기존 origin 기록을 보존하지 않는 경우

기존 origin 기록 보존이 불필요한 경우에는 현재 생성한 GitLab Repository 로 origin URL 을 변경함.

# 확인
git config --local --get user.name
git config --local --get user.email

# 설정
git config --local user.name "{MAINTAINER_NAME}"
git config --local user.email "{MAINTAINER_EMAIL}"

git remote set-url origin https://gitlab.example.com/{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}.git

7.5 필요한 branch push

  • 운영 브랜치 구조가 로컬에서 정리된 뒤 필요한 branch 를 새 GitLab Repository 로 push 함.
  • upstream 추적 설정은 운영 브랜치인 production, pre-production, develop 에 대해서만 개별 push 시 설정함
git push --set-upstream origin production
git push --set-upstream origin pre-production
git push --set-upstream origin develop
git push origin --tags

로컬의 모든 branch 를 새 GitLab Repository 로 이전해야 하는 경우에만 아래 명령을 사용할 수 있음.

git push origin --all
git push origin --tags

주의:

  • --all 은 로컬의 이전 작업 branch, 테스트 branch, 백업 branch 까지 모두 push 할 수 있음
  • 불필요 branch 가 많은 경우 --all 대신 필요한 branch 만 명시적으로 push 함

7.6 push 후 branch 상태 확인

git fetch origin --prune
git branch
git branch -r

정상 기준:

origin/develop
origin/pre-production
origin/production

8. 방식 D - 기존 Git 기록을 폐기하고 새 GitLab Repository 에 최초 연결

  • 이미 Git Repository 로 관리 중인 로컬 프로젝트 폴더에서 기존 Git 기록을 폐기하고, 현재 파일 상태만 새 GitLab Repository 의 최초 commit 으로 등록하는 절차임.
  • GitLab 빈 Repository 화면의 Push an existing folder 안내를 변형하여 수행함.
  • 기존 commit history, branch, tag, remote 기록을 보존해야 하는 경우에는 본 절차를 수행하지 않고 방식 C를 사용함.
  • 본 절차는 기존 .git 디렉터리를 백업하거나 제거한 뒤 방식 B 절차로 새 Git Repository 를 초기화하고 최초 push 하는 방식임.

주의:

  • 방식 D 는 기존 Git 기록을 폐기하는 파괴적 작업임
  • 기존 .git 디렉터리를 제거하면 기존 commit history, branch, tag, remote 기록이 현재 작업 폴더에서 끊김
  • 기존 기록을 되돌릴 가능성이 있으면 .git 디렉터리를 즉시 삭제하지 않고 먼저 백업함
  • GitLab Repository 로 push 하기 전에 .gitignore 와 제외 대상 파일을 반드시 확인함
  • 환경 파일, 인증 파일, 빌드 산출물, 로그 파일은 Repository 에 포함하지 않음

작업 위치:

{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}

8.1 기존 Git 상태 확인

현재 폴더가 기존 Git Repository 인지 확인함.

git status
git remote -v
git branch
git branch -r
git log --oneline --decorate --graph --all -n 20

확인 기준:

.git 디렉터리가 존재함
기존 origin remote 가 존재함
기존 commit history 가 존재함
기존 기록을 보존하지 않기로 결정함

8.2 기존 .git 디렉터리 백업

기존 Git 기록을 즉시 삭제하지 않고 먼저 백업함.

macOS / Linux:

mv .git .git.backup-before-new-gitlab

Windows VS Code PowerShell:

Rename-Item -Path .git -NewName .git.backup-before-new-gitlab

백업 확인:

macOS / Linux:

ls -la | grep .git

Windows VS Code PowerShell:

Get-ChildItem -Force | Where-Object { $_.Name -like ".git*" }

정상 기준:

.git.backup-before-new-gitlab

주의:

  • 백업이 필요 없다는 판단이 명확한 경우에만 .git 디렉터리를 직접 삭제할 수 있음
  • 운영 문서 기준으로는 삭제보다 백업을 기본 절차로 사용함

직접 삭제가 필요한 경우:

macOS / Linux:

rm -rf .git

Windows VS Code PowerShell:

Remove-Item -Path .git -Recurse -Force

8.3 방식 B 절차 수행

기존 .git 디렉터리 백업 또는 제거가 완료되면 방식 B 절차를 기준으로 새 Git Repository 를 초기화하고 최초 push 함.

8.4 백업 .git 디렉터리 처리

새 GitLab Repository 연결과 최초 push 가 정상 완료된 뒤 기존 Git 백업 디렉터리 보관 여부를 결정함.

보관하는 경우:

macOS / Linux:

ls -la .git.backup-before-new-gitlab

Windows VS Code PowerShell:

Get-ChildItem -Force .git.backup-before-new-gitlab

삭제하는 경우:

macOS / Linux:

rm -rf .git.backup-before-new-gitlab

Windows VS Code PowerShell:

Remove-Item -Path .git.backup-before-new-gitlab -Recurse -Force

주의:

  • 백업 .git 디렉터리를 삭제하면 기존 Git 기록 복구가 어려워짐
  • 기존 기록 폐기가 확정되기 전까지는 일정 기간 보관할 수 있음

9. 운영 브랜치 생성

본 절차는 방식 A, 방식 B, 방식 D 수행 후 적용함.

  • 방식 A, 방식 B, 방식 D 는 production 최초 push 이후 pre-production, develop 브랜치를 생성함
  • 방식 C는 7장에서 로컬 운영 브랜치 구조를 먼저 정리한 뒤 새 GitLab Repository 로 push 함

브랜치 확인:

git fetch origin --prune
git branch -a

9.1 방식 A/B/D - production 기준 운영 브랜치 생성

방식 A, 방식 B, 방식 D 를 수행한 경우에는 이미 production 브랜치가 존재해야 함.

git switch production

git switch --create pre-production
git push --set-upstream origin pre-production

git switch production
git switch --create develop
git push --set-upstream origin develop

git switch develop

정상 기준:

origin/production
origin/pre-production
origin/develop

10. Default Branch 확인

경로:

Project → Settings → Repository → Branch defaults

확인:

Default branch: production

Default Branch 가 production 이 아닌 경우 production 으로 변경함.

수행 계정 기준:

  • 운영 책임자 계정으로 수행하는 경우 해당 Project 에 13-Maintainer 권한이 있어야 함
  • Default Branch 변경 권한이 없는 경우 gitlab-admin 계정으로 수행함
  • 로컬 Git 의 원격 HEAD 정보를 origin/production 기준으로 동기화함.
git fetch origin --prune
git remote set-head origin -a

확인:

git branch -r

정상 기준:

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

11. 방식 C 불필요 브랜치 정리

  • Default Branchproduction 으로 설정된 것을 확인한 뒤 불필요 branch 를 삭제함.

정리 대상 예시:

main
master
test/*
backup/*
old/*
임시 작업 branch
운영에 사용하지 않는 이전 branch

원격 브랜치 삭제:

git push origin --delete {BRANCH_NAME}

로컬 브랜치 삭제:

git branch -D {BRANCH_NAME}

원격 브랜치 캐시 정리:

git fetch origin --prune

정상 기준:

origin/develop
origin/pre-production
origin/production