오프라인 전송으로 그룹 및 프로젝트 마이그레이션
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed
요약
이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 오프라인 전송은 원본 인스턴스와 대상 인스턴스 사이에 직접적인 네트워크 연결 없이 오브젝트 스토리지를 통해 인스턴스 간에 GitLab 그룹과 프로젝트를 복사합니다.
히스토리
- GitLab 19.3에서
offline_transfer_exports,offline_transfer_imports,offline_transfer_ui라는 기능 플래그와 함께 실험 기능으로 도입되었습니다. 기본적으로 비활성화되어 있습니다.
이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참고합니다. 이 기능은 테스트용으로 제공되며 프로덕션 환경에서 사용할 준비가 되지 않았습니다.
오프라인 전송은 원본 인스턴스와 대상 인스턴스 사이에 직접적인 네트워크 연결 없이 오브젝트 스토리지를 통해 인스턴스 간에 GitLab 그룹과 프로젝트를 복사합니다. 원본 인스턴스는 데이터를 스토리지 버킷으로 내보내고, 대상 인스턴스는 읽을 수 있는 버킷에서 데이터를 가져옵니다.
대상 인스턴스가 원본 인스턴스에 연결해야 하는 직접 전송을 통한 마이그레이션과 달리, 오프라인 전송은 내보내기와 가져오기를 분리합니다. 내보내기 버킷과 가져오기 버킷은 같은 버킷일 필요가 없으며, 같은 오브젝트 스토리지 공급자를 사용할 필요도 없습니다. 대상 인스턴스가 내보내기 버킷에 접근할 수 없으면 내보내기 파일을 대상이 접근할 수 있는 버킷으로 옮깁니다. GitLab은 이 파일을 대신 옮겨 주지 않습니다.
파일을 옮길 때 오브젝트 키 구조를 그대로 유지합니다. 오프라인 전송은 모든 오브젝트 키를 내보내기 접두사로 구성합니다.
<export_prefix>/metadata.json.gz<export_prefix>/<entity_prefix>/<relation>.<extension><export_prefix>/<entity_prefix>/<relation>/batch_<number>.<extension>
예: 2026-04-16_19-39-00_export_dJtnb3CV/project_1/repository.tar.gz
최상위 내보내기 접두사는 가져오기를 시작할 때 직접 지정하므로 이름을 바꿀 수 있습니다. 내보내기 접두사 아래의 모든 항목은 같은 구조와 파일 이름을 유지해야 합니다.
인스턴스 사이에 직접 연결이 없다고 해서 어느 한쪽 인스턴스가 오프라인이라는 뜻은 아닙니다. 원본 인스턴스와 대상 인스턴스 모두 내보내기 또는 가져오기를 수행하려면 오브젝트 스토어에 대한 네트워크 접근이 여전히 필요합니다.
오프라인 전송은 기능 플래그와 애플리케이션 설정으로 이중 제어됩니다. 모두 기본적으로 꺼져 있으며, 특정 작업을 수행하려면 두 계층이 모두 켜져 있어야 합니다.
- 내보내기:
offline_transfer_exports_enabled애플리케이션 설정. - 가져오기:
offline_transfer_imports_enabled애플리케이션 설정.
내보내기와 가져오기를 수행하려면 오프라인 전송 REST API를 사용합니다. GitLab UI에서의 오프라인 전송 지원은 작업 항목 19870에서 제안되었습니다.
버전 요구 사항#
오프라인 전송 내보내기를 만들려면 원본 인스턴스가 GitLab 19.3 이상이어야 합니다. 내보내기를 가져오려면 대상 인스턴스가 GitLab 19.3 이상이어야 합니다.
모든 내보내기에는 그것을 만든 원본 인스턴스의 버전이 기록됩니다. 해당 버전이
대상 인스턴스가 지원하는 최소 버전보다 낮으면 가져오기가
Unsupported GitLab version 오류와 함께 실패합니다.
지원되는 오브젝트 스토리지 공급자#
오프라인 전송은 다음 오브젝트 스토리지 공급자를 지원합니다.
| 공급자 | 설명 |
|---|---|
| AWS S3 | Amazon S3 오브젝트 스토리지입니다. |
| S3-compatible | MinIO와 기타 S3 호환 공급자입니다. 관리자가 S3 호환 오브젝트 스토리지를 켜야 합니다. |
| Google Cloud Storage (service account) | 서비스 계정 JSON 키로 인증하는 Google Cloud Storage입니다. |
| Google Cloud Storage (HMAC) | S3 상호 운용성 HMAC 키로 인증하는 Google Cloud Storage입니다. |
| Google Cloud Storage with Application Default Credentials | Application Default Credentials(ADC)로 인증하는 Google Cloud Storage입니다. 관리자와 특정 버킷으로 제한되며 GitLab.com에서는 사용할 수 없습니다. 자세한 내용은 Application Default Credentials를 참고합니다. |
필요한 권한#
제공하는 오브젝트 스토리지 자격 증명에는 다음 권한이 있어야 합니다.
AWS S3의 경우:
- 내보내기:
s3:PutObject및s3:ListBucket - 가져오기:
s3:GetObject및s3:ListBucket
서비스 계정을 사용하는 Google Cloud Storage의 경우:
- 내보내기:
storage.buckets.get,storage.objects.create,storage.objects.list - 가져오기:
storage.objects.get
ADC를 사용하는 Google Cloud Storage에도 같은 권한이 필요하며, 이 권한은 사용자가 제공하는 키가 아니라 인스턴스의 서비스 계정이 가집니다.
Google Cloud Storage HMAC 키는 S3 상호 운용성 API를 통해 인증하므로
storage.* 권한이 아니라 앞에 나열한 AWS S3 권한이 필요합니다.
다른 S3 호환 공급자의 권한은 공급자마다 다릅니다. 앞에 나열한 AWS S3 권한에 해당하는 읽기 및 쓰기 권한으로 공급자를 구성합니다.
Application Default Credentials#
ADC를 사용하는 Google Cloud Storage는 전송을 시작한 사용자가 아니라 GitLab을 실행하는
인스턴스의 서비스 계정으로 인증합니다. 이 서비스 계정은 보통 개별 사용자보다
권한이 높으므로, GitLab은 ADC 전송을 관리자와 이름이
gitlab-offline-transfer-로 시작하는 버킷으로 제한합니다.
관리자는 인스턴스에서 ADC도 켜야 합니다. 보안 영향과 전체 제한 사항 목록은 오프라인 전송에 Application Default Credentials 허용을 참고합니다.
마이그레이션되는 항목#
히스토리
오프라인 전송은 직접 전송을 통한 마이그레이션과 같은 그룹 및 프로젝트 항목을 가져옵니다. 전체 목록은 마이그레이션되는 그룹 항목과 마이그레이션되는 프로젝트 항목을 참고합니다.
다음 항목은 오프라인 전송으로 가져오지 않습니다.
- 위키. 위키 가져오기 지원은 작업 항목 538858에서 제안되었습니다.
그룹을 가져올 때 하위 그룹과 프로젝트가 내보내기에 있으면 항상 함께 가져옵니다.
사용자 기여 매핑#
오프라인 전송은 대상 인스턴스에 실제 사용자를 만들지 않습니다. 대신 가져온 기여는 플레이스홀더 사용자에 매핑됩니다. 가져오기가 끝난 뒤 플레이스홀더 사용자를 재할당하여 대상 인스턴스의 사용자에게 연결합니다.
오프라인 전송은 그룹 및 프로젝트 멤버십을 플레이스홀더 멤버십으로 가져옵니다. 플레이스홀더 사용자를 재할당하면 GitLab이 해당 멤버십을 대응하는 사용자에게 재할당합니다.
가시성 규칙#
오프라인 전송은 직접 전송을 통한 마이그레이션과 같은 가시성 규칙을 적용합니다. 자세한 내용은 가시성 규칙을 참고합니다.
그룹 내보내기 및 가져오기 범위#
GitLab은 중첩 깊이와 관계없이 모든 하위 그룹과 프로젝트를 포함한 그룹 구조 전체를 내보냅니다. 그룹의 하위 그룹이나 프로젝트 중 일부만 내보낼 수는 없습니다.
GitLab은 내보낸 그룹의 일부를 가져올 수 있습니다. 그룹을 여러 차례로 나누어 마이그레이션하려면 다음을 수행합니다.
- 그룹 전체를 한 번 내보냅니다.
- 가져올 때 차수마다 어떤 하위 그룹과 프로젝트를 가져올지 선택합니다.
또는 내보내기 요청에서 각 프로젝트의 전체 경로를 별도의 엔티티로 지정하여, 상위 그룹 대신 개별 프로젝트를 내보낼 수도 있습니다.
그룹 또는 프로젝트 마이그레이션#
사전 요구 사항:
- 프로젝트를 내보내려면 해당 프로젝트에서 최소한 Maintainer 권한이 있어야 합니다.
- 그룹을 내보내려면 해당 그룹의 Owner 권한이 있어야 합니다.
- 그룹으로 가져오려면 대상 그룹의 Owner 권한이 있어야 합니다.
- 그룹을 최상위 그룹으로 가져오려면 그룹을 만들 수 있는 권한이 있어야 합니다.
- 내보내기 또는 가져오기에 Application Default Credentials를 사용하려면 관리자 접근 권한이 있어야 합니다.
그룹 또는 프로젝트를 마이그레이션하려면 다음을 수행합니다.
- 원본 인스턴스에서 REST API를 사용해 오브젝트 스토리지 버킷으로 오프라인 전송 내보내기를 만듭니다.
- 내보내기가 끝나면 GitLab이 내보내기 접두사가 담긴 이메일을 보냅니다. 가져오기를 시작하려면 이 접두사가 필요합니다. 이메일을 받지 못했다면 오브젝트 스토리지 서비스에서 내보내기 접두사를 확인할 수 있습니다.
- 대상 인스턴스가 내보내기 버킷에 접근할 수 없으면 내보내기 파일을 대상이 접근할 수 있는 버킷으로 옮깁니다.
- 대상 인스턴스에서 버킷과 내보내기 접두사로 오프라인 전송 가져오기를 만듭니다.
- 직접 전송 그룹 및 프로젝트 마이그레이션 API로 가져오기를 모니터링합니다.
내보내기 전체 가져오기#
기본적으로 오프라인 전송 가져오기에는 가져올 모든 그룹 또는 프로젝트와 그 배치 위치를 나열한
entities 배열이 필요합니다. 대신 import_all 객체를 전달하면 내보내기에 있는 모든 최상위 그룹을
하위 그룹 및 프로젝트와 함께 가져와, 원본 인스턴스의 구조를 대상 네임스페이스 아래에 다시 만들 수 있습니다.
entities와 import_all 중 정확히 하나가 필요합니다.
내보내기 전체를 가져오려면 오프라인 전송 가져오기 만들기 API에
destination_namespace 속성이 있는 import_all을 전달합니다.
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--url "https://gitlab.example.com/api/v4/offline_imports" \
--data '{
"bucket": "example-bucket",
"export_prefix": "example-export-prefix",
"aws_s3_configuration": {
"aws_access_key_id": "<aws_access_key_id>",
"aws_secret_access_key": "<aws_secret_access_key>",
"region": "us-east-1"
},
"import_all": {
"destination_namespace": "dest-group"
}
}'
destination_namespace를 dest-group/subgroup처럼 기존 그룹의 전체 경로로 설정하면
해당 그룹 아래에 구조를 다시 만듭니다. 빈 문자열("")로 설정하면 구조를
새 최상위 그룹으로 다시 만듭니다.
최상위 그룹만 가져옵니다.
- 내보내기에 최상위 그룹이 내보내지지 않은 경로가 있으면(예: 내보내기에
group-a/subgroup-b는 있지만group-a는 없는 경우) GitLab은 없는 상위 그룹을 만들지 않고 해당 경로를 건너뜁니다. - 최상위 그룹의 경로가 대상 네임스페이스의 기존 그룹과 충돌하면 GitLab은 해당 그룹과 그 아래의 모든 항목을 건너뜁니다. 내보내기의 나머지는 계속 가져옵니다.
- 모든 최상위 그룹이 기존 대상 경로와 충돌하면 가져오기가 실패합니다.
- 내보내기에 최상위 그룹이 없으면 가져오기가 실패합니다.
직접 전송 그룹 및 프로젝트 마이그레이션 API로 가져오기를 모니터링합니다.
속도 제한#
오프라인 전송 내보내기와 가져오기에는 속도 제한이 적용됩니다. 자세한 내용은 구성할 수 없는 속도 제한을 참고합니다.
파일 크기 제한#
오프라인 전송 가져오기는 직접 전송을 통한 마이그레이션과 같은 최대 다운로드 파일 크기를 적용합니다. 이 제한은 각 관계(relation) 파일에 개별적으로 적용되므로, 나머지 마이그레이션은 제한 안에 들어가더라도 큰 리포지터리 번들은 이 제한에 걸릴 수 있습니다. GitLab은 가져오기 중에 제한을 확인하므로, 제한을 초과한 파일은 내보내기를 대상 환경으로 이미 옮긴 뒤에야 실패합니다.
마이그레이션에 큰 리포지터리가 포함되어 있다면 가져오기를 시작하기 전에 대상 인스턴스의 관리자에게 이 제한을 늘려 달라고 요청합니다. 자세한 내용은 직접 전송 또는 오프라인 전송 가져오기의 최대 다운로드 파일 크기를 참고합니다.
오브젝트 스토리지 버킷 수명 주기#
GitLab은 가져오기가 끝난 뒤에도 버킷에서 내보내기 파일을 삭제하지 않습니다. 내보내기에는 리포지터리 번들, LFS 오브젝트, 업로드된 파일, 디자인 번들과 함께 이슈 및 머지 리퀘스트 설명과 노트가 담긴 줄바꿈 구분 JSON(NDJSON) 파일이 포함됩니다. 버킷은 나머지 GitLab 데이터에 적용하는 것과 같은 데이터 처리 및 데이터 상주 통제로 관리합니다.
마이그레이션 후 내보내기 파일을 보존하고 삭제하는 일은 사용자의 책임입니다.
관련 주제#
문제 해결#
오프라인 전송으로 수행한 마이그레이션에 문제가 있으면 다음 섹션에서 가능한 해결 방법을 확인합니다.
오브젝트 스토리지에서 내보내기 데이터 삭제#
내보내기마다 오브젝트 스토리지에 새 접두사가 생성되므로 한 내보내기가 다른 내보내기를 덮어쓰지 않습니다. 실패한 내보내기에서 저장된 데이터를 삭제할 필요는 없지만, 삭제하면 오브젝트 스토리지 비용을 줄일 수 있습니다.
오브젝트 스토리지에서 내보내기 데이터를 제거하려면 제공한 버킷과 내보내기 API가 반환한 export_prefix로 데이터를 식별해 삭제합니다.
오브젝트 스토리지 구성에 따라 이 작업은 되돌릴 수 없을 수 있습니다.
가져오기 오류 확인#
exceptions_json.log와importer.log에서 관련 오류를 확인합니다.- Rails 콘솔에서 오류를 추출하는 방법은 직접 전송 마이그레이션 문제 해결을 참고합니다.
가져오기 재시도#
가져오기를 재시도하려면 다음을 수행합니다.
-
재시도할 그룹이나 프로젝트를 삭제합니다. 전체 가져오기를 재시도하거나 일부 그룹 또는 프로젝트만 대상으로 할 수 있습니다.
-
REST API를 사용해 전체 가져오기를 재시도하거나,
entities매개변수에 이전에 실패한 엔티티만 지정합니다.