• 알려진 문제
• 내보내기 파일 업로드를 통한 프로젝트 마이그레이션
  • 사용자 기여도 보존하기
    • GitLab 자체 관리에서 GitLab.com으로 마이그레이션할 때
    • GitLab 자체 관리로 마이그레이션할 때
  • 프로젝트 내보내기 파일 편집
  • 호환성
  • 파일 내보내기를 가져오기 원본으로 구성하기
  • CE와 EE 간의 차이
  • 프로젝트 및 데이터 내보내기
    • 내보내기된 프로젝트 항목
    • 내보내기되지 않는 프로젝트 항목
  • 프로젝트 및 데이터 가져오기
    • 전제 조건
    • 프로젝트 가져오기
    • 가져온 항목의 변경 사항
    • 대형 프로젝트 가져오기
  • 최대 가져오기 파일 크기 설정
  • 속도 제한
• 그룹을 내보내기 파일 업로드로 마이그레이션하기 (더 이상 사용되지 않음)
  • 추가 정보
  • 호환성
  • 내보낸 그룹 항목
  • 내보내지 않는 그룹 항목
  • 준비
  • 그룹 내보내기
  • 그룹 가져오기
  • 비율 제한
• 관련 주제

파일 내보내기를 사용하여 프로젝트 및 그룹 마이그레이션

그룹 및 프로젝트를 직접 전송 방식으로 마이그레이션하는 것이 권장됩니다. 하지만 특정 상황에서는 파일 내보내기를 사용하여 그룹과 프로젝트를 마이그레이션해야 할 수도 있습니다.

알려진 문제

• 알려진 문제로 인해, PG::QueryCanceled: ERROR: canceling statement due to statement timeout 오류가 발생할 수 있습니다.
  자세한 내용은 문제 해결 문서를 참조하세요.
• GitLab 17.0, 17.1 및 17.2에서는 가져온 에픽과 작업 항목이 원래 저자가 아닌 가져오는 사용자에 매핑됩니다.

내보내기 파일 업로드를 통한 프로젝트 마이그레이션

기존 프로젝트는 모든 자체 관리 GitLab 인스턴스 또는 GitLab.com에서 파일로 내보내지고
다른 GitLab 인스턴스에 가져올 수 있습니다.

사용자 기여도 보존하기

사용자 기여도를 보존하기 위한 요구 사항은 GitLab.com으로 마이그레이션하는지
아니면 GitLab 자체 관리 인스턴스로 마이그레이션하는지에 따라 다릅니다.

GitLab 자체 관리에서 GitLab.com으로 마이그레이션할 때

파일 내보내기를 사용하여 프로젝트를 마이그레이션할 때는
사용자 기여도를 올바르게 매핑하기 위해 관리자의 액세스 토큰이 필요합니다.

따라서, 자체 관리 인스턴스에서 GitLab.com으로 파일 내보내기를 가져올 경우
사용자 기여도가 올바르게 매핑되지 않습니다. 대신 모든 GitLab 사용자 연관(예: 댓글 작성자)은
프로젝트를 가져오는 사용자로 변경됩니다. 기여 기록을 보존하려면 다음 중 하나를 수행하세요:

• 직접 전송을 사용하여 마이그레이션하기.
• 전문 서비스를 이용하는 것을 고려하세요. 자세한 내용은
  전문 서비스 전체 카탈로그를 참조하세요.

GitLab 자체 관리로 마이그레이션할 때

GitLab이 사용자와 그들의 기여도를 올바르게 매핑하도록 하려면:

• 프로젝트의 상위 그룹 소유자는 프로젝트를 내보내야 하며, 프로젝트에 액세스할 수 있는 모든 구성원의 정보(직접 및 상속)를 포함할 수 있도록 내보낸 파일에 포함되어야 합니다.
  프로젝트 유지 관리자 및 소유자는 프로젝트 내보내기를 시작할 수 있습니다. 그러나 직접 구성원만 내보내집니다.
• 가져오기는 관리자가 수행해야 합니다.
• 필요한 사용자는 대상 GitLab 인스턴스에 있어야 합니다. 관리자는 Rails 콘솔에서 일괄로 확인된 사용자를 만들거나 UI에서 하나씩 만들 수 있습니다.
• 사용자는 소스 GitLab 인스턴스에서 프로필에 공용 이메일을 설정해야 하며,
  이 이메일 주소는 대상 GitLab 인스턴스의 기본 이메일 주소와 일치해야 합니다. 또한 프로젝트 내보내기 파일 편집하기를 통해 사용자의 공용 이메일을 수동으로 추가할 수 있습니다.

기존 사용자의 이메일이 가져온 사용자의 이메일과 일치하면 해당 사용자는 가져온 프로젝트에
직접 구성원으로 추가됩니다.

이전 조건 중 하나라도 충족되지 않으면 사용자 기여도가 올바르게 매핑되지 않습니다. 대신 모든 GitLab 사용자 연관은 가져온 사용자가 수행한 작업으로 변경됩니다.
그 사용자는 다른 사용자가 만든 병합 요청의 저자가 됩니다. 원래 저자를 언급하는 보조 댓글은 다음과 같습니다:

• 댓글, 병합 요청 승인, 연결된 작업 및 항목에 추가됩니다.
• 병합 요청 또는 문제 작성자, 추가되거나 제거된 레이블, 병합된 정보에 대해서는 추가되지 않습니다.

프로젝트 내보내기 파일 편집

내보내기 파일에서 데이터를 추가하거나 제거할 수 있습니다. 예를 들어, 다음과 같이 할 수 있습니다:

• project_members.ndjson 파일에 사용자의 공개 이메일을 수동으로 추가합니다.
• ci_pipelines.ndjson 파일에서 줄을 제거하여 CI 파이프라인을 잘라냅니다.

프로젝트 내보내기 파일을 편집하려면:

1. 내보낸 .tar.gz 파일을 추출합니다.
2. 적절한 파일을 편집합니다. 예를 들어, tree/project/project_members.ndjson.
3. 파일을 다시 .tar.gz 파일로 압축합니다.

모든 구성원이 내보내졌는지 확인하려면 project_members.ndjson 파일을 확인할 수 있습니다.

호환성

• JSON 형식의 프로젝트 파일 내보내기 지원이 제거되었습니다 (GitLab 15.11).

프로젝트 파일 내보내기는 NDJSON 형식입니다.

최대 두 개의 이전 마이너 버전에서 내보낸 프로젝트 파일 내보내기를 가져올 수 있습니다.

예를 들어:

대상 버전	호환 가능한 소스 버전
13.0	13.0, 12.10, 12.9
13.1	13.1, 13.0, 12.10

파일 내보내기를 가져오기 원본으로 구성하기

세부사항: Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

파일 내보내기를 사용하여 자가 관리형 GitLab 인스턴스에서 프로젝트를 마이그레이션하기 전에, GitLab 관리자는 다음을 수행해야 합니다:

1. 파일 내보내기 활성화 소스 인스턴스에서.
2. 대상 인스턴스에 대한 가져오기 원본으로 파일 내보내기를 활성화합니다. GitLab.com에서는 파일 내보내기가 이미 가져오기 원본으로 활성화되어 있습니다.

대상 인스턴스에 대한 가져오기 원본으로 파일 내보내기를 활성화하려면:

1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
2. Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. Import sources로 스크롤합니다.
5. GitLab export 체크박스를 선택합니다.

CE와 EE 간의 차이

커뮤니티 에디션에서 엔터프라이즈 에디션으로 프로젝트를 내보낼 수 있으며, 그 반대도 가능합니다. 단, 호환성이 충족되어야 합니다.

엔터프라이즈 에디션에서 커뮤니티 에디션으로 프로젝트를 내보내는 경우, 엔터프라이즈 에디션에만 유지되는 데이터가 손실될 수 있습니다. 자세한 내용은 EE에서 CE로 다운그레이드하기를 참고하세요.

프로젝트 및 데이터 내보내기

프로젝트를 가져오려면 먼저 내보내야 합니다.

전제 조건:

• 내보내기 항목 목록을 검토합니다. 모든 항목이 내보내지지는 않습니다.
• 프로젝트에 대해 최소한 Maintainer 역할을 보유해야 합니다.

프로젝트 및 데이터를 내보내려면 다음 단계를 따르세요:

1. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. Settings > General을 선택합니다.
3. Advanced를 확장합니다.
4. Export project를 선택합니다.
5. 내보내기가 생성된 후, 다음을 수행할 수 있습니다:
   • 수신해야 하는 이메일에 포함된 링크를 따라갑니다.
   • 프로젝트 설정 페이지를 새로고침하고 Export project 영역에서 Download export를 선택합니다.

내보내기는 구성된 shared_path, 임시 공유 디렉토리에서 생성된 후, 구성된 uploads_directory로 이동됩니다. 24시간마다 작업자가 이러한 내보내기 파일을 삭제합니다.

내보내기된 프로젝트 항목

내보내기된 프로젝트 항목은 사용 중인 GitLab 버전에 따라 다릅니다. 특정 프로젝트 항목이 내보내기되는지 확인하려면:

1. exporters 배열를 확인하세요.

2. 사용 중인 GitLab 버전의 프로젝트용 project/import_export.yml 파일을 확인하세요. 예를 들어, GitLab 16.8의 경우 https://gitlab.com/gitlab-org/gitlab/-/blob/16-8-stable-ee/lib/gitlab/import_export/project/import_export.yml을 참조하세요.

간략한 개요를 위해 내보내기되는 항목은 다음과 같습니다:

• 프로젝트 및 위키 리포지토리

• 프로젝트 업로드

• 통합을 제외한 프로젝트 구성

• 이슈
  • 이슈 댓글
  • 이슈 반복 (도입됨 in GitLab 15.4)
  • 이슈 리소스 상태 이벤트 (도입됨 in GitLab 15.4)
  • 이슈 리소스 마일스톤 이벤트 (도입됨 in GitLab 15.4)
  • 이슈 리소스 반복 이벤트 (도입됨 in GitLab 15.4)
• Merge 요청
  • Merge 요청 diffs
  • Merge 요청 댓글
  • Merge 요청 리소스 상태 이벤트 (도입됨 in GitLab 15.4)
  • Merge 요청 다수의 지정자 (도입됨 in GitLab 15.3)
  • Merge 요청 리뷰어 (도입됨 in GitLab 15.3)
  • Merge 요청 승인자 (도입됨 in GitLab 15.3)

• 커밋 댓글 (도입됨 in GitLab 15.10)

• 라벨

• 마일스톤

• 스니펫

• 릴리즈

• 시간 추적 및 기타 프로젝트 엔터티

• 디자인 관리 파일 및 데이터

• LFS 객체

• 이슈 보드

• CI/CD 파이프라인 및 파이프라인 일정

• 보호된 브랜치 및 태그

• 푸시 규칙

• 이모지 반응

• 직접 프로젝트 구성원
  (내보내기된 프로젝트의 그룹에 대해 최소한 Maintainer 역할이 있어야 합니다.)

• 상속된 프로젝트 구성원으로서의 직접 프로젝트 구성원
  (내보내기된 프로젝트의 그룹에 대해 Owner 역할이 있거나 인스턴스에 대한 관리자 접근 권한이 있어야 합니다.)

• 일부 Merge 요청 승인 규칙:

  • 보호된 브랜치에 대한 승인

  • 적격 승인자

내보내기되지 않는 프로젝트 항목

내보내기되지 않는 항목은 다음과 같습니다:

• 하위 파이프라인 기록

• 파이프라인 트리거

• 빌드 추적 및 아티팩트

• 패키지 및 컨테이너 레지스트리 이미지

• CI/CD 변수

• 웹후크

• 모든 암호화된 토큰

• 필요한 승인 수

• 리포지토리 크기 제한

• 보호된 브랜치에 푸시할 수 있는 배포 키

• 보안 파일

• Git 관련 이벤트에 대한 활동 로그 (예: 푸시 및 태그 생성)

• 프로젝트와 관련된 보안 정책

• 이슈와 링크된 항목 간의 링크

• 관련 Merge 요청에 대한 링크

파일 내보내기가 포함된 프로젝트 마이그레이션은 그룹 및 인스턴스 수준에서 템플릿으로 프로젝트를 생성하는 것과 동일한 내보내기 및 가져오기 메커니즘을 사용합니다. 따라서 내보내기 항목 목록은 동일합니다.

프로젝트 및 데이터 가져오기

프로젝트 및 데이터를 가져올 수 있습니다. 가져올 수 있는 데이터 양은 최대 가져오기 파일 크기에 따라 다릅니다:

• GitLab 자가 관리 인스턴스에서, 자가 관리 인스턴스의 관리자는 최대 가져오기 파일 크기 설정하기 할 수 있습니다.
• GitLab.com에서는 값이 5 GB로 설정되어 있습니다.

경고: 신뢰하는 소스의 프로젝트만 가져오세요. 신뢰할 수 없는 소스에서 프로젝트를 가져오면 공격자가 귀하의 민감한 데이터를 도용할 수 있습니다.

전제 조건

• GitLab 16.0에서 도입된 Maintainer 역할에 대한 요구 사항으로, GitLab 15.11.1 및 GitLab 15.10.5에 대해 백포트되었습니다.

• 프로젝트 및 데이터 내보내기를 완료해야 합니다.
• GitLab 버전을 비교하고 내보낸 GitLab 버전과 동일하거나 최신의 GitLab 버전으로 가져오고 있는지 확인하세요.
• 문제를 위해 호환성을 검토하세요.
• 마이그레이션할 대상 그룹에서 최소한 Maintainer 역할을 가져야 합니다.

프로젝트 가져오기

프로젝트를 가져오려면:

1. 왼쪽 사이드바에서 맨 위의 새로 만들기() 및 새 프로젝트/저장소를 선택합니다.
2. 프로젝트 가져오기를 선택합니다.
3. 가져올 프로젝트에서 GitLab 내보내기를 선택합니다.
4. 프로젝트 이름과 URL을 입력합니다. 그리고 이전에 내보낸 파일을 선택합니다.
5. 프로젝트 가져오기를 선택합니다.

API를 사용하여 가져오기 상태를 조회할 수 있습니다. 쿼리는 가져오기 오류 또는 예외를 반환할 수 있습니다.

가져온 항목의 변경 사항

내보낸 항목은 다음 변경 사항으로 가져옵니다:

• 소유자 역할을 가진 프로젝트 구성원은 Maintainer 역할로 가져옵니다.
• 가져온 프로젝트에 포크에서 유래된 병합 요청이 포함된 경우, 이러한 병합 요청과 관련된 새로운 브랜치가 프로젝트에 생성됩니다. 따라서 새로운 프로젝트의 브랜치 수는 원본 프로젝트보다 많을 수 있습니다.
• Internal 가시성 수준이 제한된 경우, 모든 가져온 프로젝트는 Private 가시성을 갖습니다.

배포 키는 가져오지 않습니다. 배포 키를 사용하려면 가져온 프로젝트에서 이를 활성화하고 보호된 브랜치를 업데이트해야 합니다.

대형 프로젝트 가져오기

더 큰 프로젝트가 있는 경우 Rake 작업 사용하기를 고려하세요.

최대 가져오기 파일 크기 설정

관리자는 두 가지 방법 중 하나로 최대 가져오기 파일 크기를 설정할 수 있습니다:

• 애플리케이션 설정 API에서 max_import_size 옵션을 사용하여.
• 관리자 영역 UI에서.

기본값은 0(무제한)입니다.

속도 제한

악용을 방지하기 위해 기본적으로 사용자는 다음과 같은 속도 제한이 적용됩니다:

요청 유형	제한
내보내기	분당 6개의 프로젝트
내보내기 다운로드	그룹당 분당 1회의 다운로드
가져오기	분당 6개의 프로젝트

그룹을 내보내기 파일 업로드로 마이그레이션하기 (더 이상 사용되지 않음)

• 더 이상 사용되지 않음 GitLab 14.6에서.

경고:

이 기능은 더 이상 사용되지 않음 GitLab 14.6에서 되었으며 직접 전송으로 그룹 마이그레이션하기로 대체되었습니다. 그러나 이 기능은 오프라인 시스템 간 그룹 마이그레이션을 위해 여전히 권장됩니다. 오프라인 환경에 대한 대안 솔루션의 진행 상황을 보려면 관련 에픽을 참조하세요.

전제 조건:

• 마이그레이션할 그룹의 소유자 역할.

파일 내보내기를 사용하여 다음을 수행할 수 있습니다:

• 그룹을 파일로 내보내고 해당 파일을 다른 GitLab 인스턴스나 동일 인스턴스의 다른 위치에 업로드합니다.
• GitLab UI 또는 API를 사용할 수 있습니다.
• 그룹을 하나씩 마이그레이션한 후, 각 그룹에 대한 프로젝트를 각각 내보내고 가져옵니다.

GitLab은 관리 액세스 토큰을 사용하여 가져오기를 수행할 때 사용자 기여도를 정확하게 매핑합니다. GitLab은 self-managed 인스턴스에서 GitLab.com으로 가져오는 경우 사용자 기여도를 정확하게 매핑하지 않습니다. self-managed 인스턴스에서 GitLab.com으로 가져올 때 사용자 기여도의 올바른 매핑은 Professional Services 팀의 유료 참여로 보존될 수 있습니다.

추가 정보

• 내보내기는 임시 디렉토리에 저장되며 특정 작업자에 의해 매 24시간마다 삭제됩니다.
• 가져온 프로젝트의 그룹 수준 관계를 보존하려면 그룹을 먼저 내보내고 가져와서 프로젝트를 원하는 그룹 구조에 가져옵니다.
• 가져온 그룹은 private 가시성 수준을 부여받습니다. 단, 부모 그룹에 가져온 경우는 제외합니다.
• 부모 그룹에 가져온 경우, 하위 그룹은 별도로 제한되지 않는 한 동일한 가시성 수준을 상속받습니다.
• Community Edition에서 Enterprise Edition으로 그룹을 내보내고 그 반대의 경우도 가능합니다. Enterprise Edition은 Community Edition의 일부가 아닌 그룹 데이터를 유지합니다. Enterprise Edition에서 Community Edition으로 그룹을 내보낼 경우, 이 데이터를 잃을 수 있습니다. 자세한 내용은 EE에서 CE로 다운그레이드하기를 참조하세요.

최대 가져오기 파일 크기는 GitLab self-managed 인스턴스 또는 GitLab.com으로 가져오는지에 따라 다릅니다:

• GitLab self-managed 인스턴스로 가져오는 경우, 크기가 어떤 가져오기 파일이든 가져올 수 있습니다. 관리자는 다음을 사용하여 이 동작을 변경할 수 있습니다:
  • 응용 프로그램 설정 API의 max_import_size 옵션.
  • 관리자 영역.
• GitLab.com에서는 크기가 5 GB를 초과하지 않는 가져오기 파일을 사용하여 그룹을 가져올 수 있습니다.

호환성

• JSON 형식의 프로젝트 파일 내보내기 지원 제거됨 GitLab 15.8에서.

그룹 파일 내보내기는 NDJSON 형식입니다.

GitLab의 두 번째 마이너 버전까지 내보내진 그룹 파일 내보내기를 가져올 수 있습니다.

예를 들어:

목적지 버전	호환 가능한 소스 버전
13.0	13.0, 12.10, 12.9
13.1	13.1, 13.0, 12.10

내보낸 그룹 항목

그룹을 내보낼 때 내보내고 가져올 항목을 나열한 import_export.yml 파일이 있습니다.

파일 내보내기를 사용하여 그룹을 마이그레이션할 때 가져올 수 있는 항목을 확인하려면 GitLab의 해당 버전 브랜치에서 이 파일을 확인하세요. 예를 들어, 16-8-stable-ee 브랜치의 import_export.yml입니다.

내보낸 그룹 항목에는 다음이 포함됩니다:

• 마일스톤
• 그룹 레이블 (연관된 레이블 우선 순위 없음)
• 보드 및 보드 목록
• 배지
• 하위 그룹 (위의 모든 데이터 포함)
• 에픽
  • 에픽 리소스 상태 이벤트. 도입됨 GitLab 15.4에서.
• 이벤트
• 위키
• 반복 주기. 도입됨 GitLab 15.4에서.

내보내지 않는 그룹 항목

내보내지 않는 항목은 다음과 같습니다:

• 프로젝트
• 러너 토큰
• SAML 검색 토큰
• 업로드

준비

• 가져온 그룹에서 멤버 목록과 그에 대한 권한을 보존하려면 이 그룹의 사용자 목록을 검토하세요.

  원하는 그룹을 가져오기 전에 이러한 사용자가 존재하는지 확인하세요.

• 사용자는 소스 GitLab 인스턴스에서 공용 이메일을 설정해야 하며, 이는 대상 GitLab 인스턴스에서 확인된 기본 이메일과 일치해야 합니다. 대부분의 사용자는 이메일 주소 확인 요청을 포함한 이메일을 받을 수 있습니다.

그룹 내보내기

사전 조건:

• 그룹의 소유자 역할이 있어야 합니다.

그룹의 내용을 내보내려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 설정 > 일반을 선택합니다.
3. 고급 섹션에서 그룹 내보내기를 선택합니다.
4. 내보내기가 생성된 후, 다음 중 하나를 선택할 수 있습니다:
   • 이메일에 포함된 링크를 따릅니다.
   • 그룹 설정 페이지를 새로 고쳐서 프로젝트 내보내기 영역에서 내보내기 다운로드를 선택합니다.

그룹 가져오기

그룹을 가져오려면:

1. 왼쪽 사이드바 상단에서 새로 만들기 () 및 새 그룹을 선택합니다.
2. 그룹 가져오기를 선택합니다.
3. 파일에서 그룹 가져오기 섹션에서 그룹 이름을 입력하고 연관된 그룹 URL을 수락하거나 수정합니다.
4. 파일 선택을 선택합니다.
5. 가져오고자 하는 GitLab 내보내기 파일을 선택합니다.
6. 가져오기를 시작하려면 가져오기를 선택합니다.

비율 제한

남용을 방지하기 위해 기본적으로 사용자에게 비율 제한을 설정합니다:

요청 유형	한도
내보내기	분당 6 그룹
내보내기 다운로드	분당 그룹당 1 다운로드
가져오기	분당 6 그룹

관련 주제

• 프로젝트 가져오기 및 내보내기 API
• 프로젝트 가져오기 및 내보내기 관리 Rake 작업
• GitLab 그룹 마이그레이션
• 그룹 가져오기 및 내보내기 API
• 직접 전송으로 그룹 마이그레이션.