Git 레포지토리 GitLab 마이그레이션 가이드

Overview

이 가이드는 기존 Git 레포지토리(GitHub, Bitbucket 등)를 GitLab으로 안전하게 마이그레이션하는 방법을 제공한다. 특히 대용량 LFS 파일이 포함된 레포지토리나 네트워크 안정성이 중요한 환경에서 사용하기 적합하다.

 

 

 

 

Mirroring 방법은 아래의 글을 참고하길 바란다.

2025.01.09 - [IaC/CI CD Tool] - 8. Gitlab Repository Mirroring 방법

 

 

Github → Gitlab Mirroring 방법은 아래와 같다.

• Mirroring Workflow 실행 전에 Gitlab에 설정을 해야한다.
• Gitlab 계정 생성 및 Group , Project 생성
• Gitlab Token 생성

name: Backup GitHub to GitLab

on:
  push:
    branches:
      - main  # main 브랜치 변경 시 동기화
    paths-ignore:
      - .github/workflows/*
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout GitHub Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 전체 히스토리를 가져오도록 설정
          lfs: true      # Git LFS 파일도 가져오기
          
      - name: Configure Git
        run: |
          git config --global user.name "GitHub Action"
          git config --global user.email "action@github.com"

      - name: Push to GitLab Mirror
        env:
          GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}
        run: |
          git remote add gitlab https://oauth2:${GITLAB_TOKEN}@gitlab.com/backup6695808/compress-decompress.git
          git push -f --all gitlab  # 모든 브랜치 푸시 (하지만 강제 덮어쓰지는 않음)
          git push -f --tags gitlab  # 모든 태그 푸시
        continue-on-error: true

 

 

 

이런 상황에서 사용하세요

• 대용량 LFS 파일(GB 단위)이 포함된 레포지토리
• 느린 네트워크 환경에서의 마이그레이션
• 여러 브랜치와 태그가 있는 복잡한 레포지토리
• 마이그레이션 실패 위험을 최소화하고 싶은 경우

 

 

핵심 특징

• 안전성: 로컬에 전체 데이터 복사 후 진행
• 효율성: 네트워크 다운로드는 한 번만, 업로드만 새 서버로
• 완전성: 모든 브랜치, 태그, LFS 오브젝트 포함

 

 

 

 

 

---

 

 

마이그레이션 워크플로우

1. 기존 원격 저장소 → 모든 데이터 로컬로 완전 복사
2. Remote URL 변경 → GitLab으로 설정
3. GitLab으로 전체 푸시 → 완료

용량이 큰 레포지토리나 네트워크 이슈가 있을 때 사용하는 안전한 마이그레이션 방법

 

 

 

 

 

 

1. 브랜치 준비 및 LFS 마이그레이션

 

1.1 모든 원격 브랜치 로컬로 체크아웃

# 원격 브랜치를 로컬로 모두 체크아웃하거나 트래킹 브랜치 생성
for b in $(git branch -r | grep -v '\\->' | grep -v master); do
  git checkout --track "$b" || echo "Skip $b"
done

 

 

 

1.2 LFS 오브젝트 처리

# 모든 데이터 가져오기
git fetch --all

# LFS 오브젝트들 모두 로컬로 받아오기
git lfs fetch --all
git lfs checkout  # 선택사항

 

 

 

1.3 Remote URL 변경

# 현재 remote 확인
git remote -v

# 기존 origin을 GitLab으로 변경
git remote set-url origin git@gitlab.somaz.link:<group>/<project>.git

# 변경 확인
git remote -v

# LFS 설정 업데이트
git config lfs.<https://gitlab.somaz.link/(gruop>/(project).git/info/lfs.locksverify> true

 

 

 

1.4 GitLab으로 푸시

# GitLab으로 모든 LFS 오브젝트 업로드
git lfs push --all origin

# GitLab으로 Git 히스토리 전체 강제 push
git push -f --all origin

# 모든 태그 푸시
git push --tags origin

# 마스터 브랜치만 푸시 (필요시)
git push -f origin master

 

 

 

 

 

 

2. LFS 파일 확인 명령어

 

 

2.1 LFS 파일 목록 및 크기 확인

# LFS 파일 목록과 크기 표시
git lfs ls-files --size

# 총 MB 계산
git lfs ls-files --size | sed -n 's/.*(\\([0-9.]*\\) MB)/\\1/p' | awk '{sum += $1} END {print sum, "MB total"}'

# 총 GB 계산 (소수점 2자리)
git lfs ls-files --size | sed -n 's/.*(\\([0-9.]*\\) MB)/\\1/p' | awk '{sum += $1} END {printf "%.2f GB total\\n", sum / 1024}'

 

 

 

 

 

 

 

3. GitLab 서버 설정 조정

 

 

3.1 GitLab 설정 파일 수정 (`/etc/gitlab/gitlab.rb`)

# Git push/pull 타임아웃 설정 (초 단위)
gitlab_rails['gitlab_shell_git_timeout'] = 10800  # 3시간 (기본값: 3600초)

# HTTP 요청 타임아웃 설정
unicorn['worker_timeout'] = 300  # 5분

# LFS 관련 타임아웃 설정
gitlab_rails['lfs_object_store_connection_timeout'] = 600  # 10분

# 대용량 파일 푸시 허용 설정 (바이트 단위)
gitlab_rails['max_size_in_bytes'] = 20_000_000_000  # 20GB

# pre-receive 훅 타임아웃 설정
gitlab_rails['webhook_timeout'] = 180  # 3분

 

 

 

 

3.2 설정 적용

# GitLab 설정 재구성
sudo gitlab-ctl reconfigure

# GitLab 재시작
sudo gitlab-ctl restart

 

 

 

 

4. LFS 비활성화 (필요시)

• LFS 비활성화가 필요한 경우는 용량이 큰데 LFS 설정이 안되어 있는 레포를 옮길 경우이다.
• 그 이유는 용량이 큰데 LFS 설정이 되어있지 않으면 Gitlab은 자동으로 LFS API를 호출하고 에러가 발생한다.

 

4.1 GitLab 웹 UI에서 LFS 비활성화

 

관리자 권한 필요

1. http://gitlab.concrit.us/<group>/<project> 접속
2. Settings → General 메뉴
3. "Visibility, project features, permissions" 섹션 확장
4. Large File Storage (LFS) 항목을 Off로 설정

 

 

 

 

 

주의사항

• 완전 로컬 복사: 기존 원격 저장소에서 모든 브랜치와 LFS 데이터를 로컬에 완전히 가져온 후 remote 변경
• 대용량 데이터 안전성: 용량이 큰 레포지토리의 경우 이 방식이 더 안전하고 효율적
• 대용량 LFS 파일이 있는 경우 네트워크 타임아웃이 발생할 수 있으므로 서버 설정 조정이 필요
• 강제 푸시(-f 옵션) 사용 시 기존 데이터가 덮어써질 수 있으니 주의
• LFS 오브젝트 마이그레이션은 시간이 오래 걸릴 수 있음

 

 

 

 

 

 

마이그레이션 완료 후 확인사항

 

1. 데이터 무결성 확인

# 브랜치 확인
git branch -a

# 태그 확인  
git tag

# LFS 파일 확인
git lfs ls-files --size

# 최근 커밋 확인
git log --oneline -10

 

 

 

2. GitLab에서 확인

• Repository → 모든 브랜치와 태그가 정상적으로 표시되는지 확인
• Settings → Repository → Repository size 확인
• LFS 오브젝트 크기 확인

 

 

 

 

 

 

문제 해결

 

LFS 푸시 실패 시

# LFS 인증 정보 초기화
git config --unset lfs.{gitlab_url}.access

# 다시 시도
git lfs push --all origin

 

 

 

타임아웃 발생 시

• GitLab 서버 설정의 타임아웃 값 증가
• 브랜치별로 나누어서 푸시 시도

 

용량 제한 오류 시

• GitLab 관리자에게 `max_size_in_bytes` 설정 증가 요청
• 또는 LFS 기능 비활성화 후 진행

 

 

 

 

 

 

---

Reference

• Atlassian Community - Bitbucket to GitLab Migration