임포트 및 익스포트 관련 기능의 설정입니다.

허용된 임포트 소스 구성#

다른 시스템에서 프로젝트를 임포트하려면 먼저 해당 시스템의 임포트 소스를 활성화해야 합니다.

1. GitLab에 관리자 액세스 레벨 사용자로 로그인합니다.
2. 오른쪽 상단에서 Admin을 선택합니다.
3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
4. Import and export settings 섹션을 확장합니다.
5. 허용할 Import sources를 각각 선택합니다.
6. Save changes를 선택합니다.

사용하지 않는 임포트 소스 비활성화#

신뢰하는 소스에서만 프로젝트를 임포트합니다. 신뢰할 수 없는 소스에서 프로젝트를 임포트하면 공격자가 민감한 데이터를 훔칠 수 있습니다. 예를 들어 악성 .gitlab-ci.yml 파일이 포함된 임포트 프로젝트는 공격자가 그룹 CI/CD 변수를 빼내도록 허용할 수 있습니다.

GitLab Self-Managed 관리자는 필요하지 않은 임포트 소스를 비활성화해 공격 표면을 줄일 수 있습니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. Import sources로 스크롤합니다.
5. 필요하지 않은 임포터의 체크박스를 선택 해제합니다.

프로젝트 익스포트 활성화#

프로젝트와 그 데이터의 익스포트를 활성화하려면 다음과 같이 합니다.

1. GitLab에 관리자 액세스 레벨 사용자로 로그인합니다.
2. 오른쪽 상단에서 Admin을 선택합니다.
3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
4. Import and export settings 섹션을 확장합니다.
5. Project export로 스크롤합니다.
6. Enabled 체크박스를 선택합니다.
7. Save changes를 선택합니다.

직접 전송으로 그룹 및 프로젝트 마이그레이션 활성화#

히스토리

• GitLab 18.3에서 일반적으로 사용 가능해졌습니다.

직접 전송을 통한 그룹 및 프로젝트 마이그레이션은 기본적으로 비활성화됩니다. 직접 전송으로 그룹과 프로젝트를 마이그레이션하는 기능을 활성화하려면 다음과 같이 합니다.

1. GitLab에 관리자 액세스 레벨 사용자로 로그인합니다.
2. 오른쪽 상단에서 Admin을 선택합니다.
3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
4. Import and export settings 섹션을 확장합니다.
5. Allow migrating GitLab groups and projects by direct transfer로 스크롤합니다.
6. Enabled 체크박스를 선택합니다.
7. Save changes를 선택합니다.

같은 설정을 API에서도 bulk_import_enabled 속성으로 사용할 수 있습니다.

오프라인 전송을 위한 그룹 및 프로젝트 익스포트 활성화#

히스토리

• GitLab 19.3에서 offline_transfer_exports라는

사전 요구 사항:

• 관리자여야 합니다.

사용자가 그룹과 프로젝트의 오프라인 전송 익스포트를 만들 수 있도록 이 설정을 켭니다.

오프라인 전송을 위한 그룹 및 프로젝트 익스포트를 활성화하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings 섹션을 확장합니다.
4. Allow exporting GitLab groups and projects by offline transfer로 스크롤합니다.
5. Enabled 체크박스를 선택합니다.
6. Save changes를 선택합니다.

같은 설정을 API에서도 offline_transfer_exports_enabled 속성으로 사용할 수 있습니다.

오프라인 전송으로 그룹 및 프로젝트 임포트 활성화#

히스토리

• GitLab 19.3에서 offline_transfer_imports라는

사전 요구 사항:

• 관리자여야 합니다.

사용자가 오프라인 전송 익스포트에서 그룹과 프로젝트를 임포트할 수 있도록 이 설정을 켭니다.

오프라인 전송으로 그룹 및 프로젝트 임포트를 활성화하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings 섹션을 확장합니다.
4. Allow importing GitLab groups and projects by offline transfer로 스크롤합니다.
5. Enabled 체크박스를 선택합니다.
6. Save changes를 선택합니다.

같은 설정을 API에서도 offline_transfer_imports_enabled 속성으로 사용할 수 있습니다.

오프라인 전송에 S3 호환 오브젝트 스토리지 허용#

히스토리

• GitLab 18.9에서 offline_transfer_exports라는

사전 요구 사항:

• 관리자여야 합니다.

기본적으로 오프라인 전송은 AWS S3와 Google Cloud Storage만 지원합니다. 이 설정을 켜면 MinIO처럼 S3 호환 공급자도 허용할 수 있습니다.

오프라인 전송에 S3 호환 오브젝트 스토리지를 허용하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings 섹션을 확장합니다.
4. Allow S3 compatible object storage for offline transfer로 스크롤합니다.
5. Enabled 체크박스를 선택합니다.
6. Save changes를 선택합니다.

오프라인 전송에 애플리케이션 기본 자격 증명 허용#

히스토리

• GitLab 19.3에서 offline_transfer_exports, offline_transfer_imports, offline_transfer_ui라는 기능 플래그와 함께 실험으로 도입됐습니다. 기본적으로 비활성화됩니다.

오프라인 전송이 Application Default Credentials(ADC)를 사용해 Google Cloud Storage에 인증하도록 허용하려면 이 설정을 켭니다.

다른 모든 오브젝트 스토리지 공급자에서는 익스포트나 임포트를 만드는 사용자가 자격 증명을 제공합니다. ADC에서는 어떤 사용자도 자격 증명을 제공하지 않습니다. GitLab은 Google Cloud 프로젝트 ID만 저장하고, 요청마다 Compute Engine 메타데이터 서버나 GOOGLE_APPLICATION_CREDENTIALS 환경 변수 같은 인스턴스 환경에서 자격 증명을 확인합니다.

사전 요구 사항:

• 관리자여야 합니다.

이 위험을 제한하기 위해 GitLab은 끌 수 없는 다음 제한을 적용합니다.

• 관리자 액세스 권한이 있는 사용자만 ADC를 사용하는 오프라인 전송 익스포트나 임포트를 만들 수 있습니다. 다른 사용자는 Only administrators can use Application Default Credentials for offline transfer. 오류를 받습니다.
• 버킷 이름은 gitlab-offline-transfer-로 시작해야 합니다. 이 접두사는 ADC 전송을 인스턴스가 업로드, job 아티팩트, LFS 오브젝트처럼 자체 오브젝트 스토리지로 사용하는 버킷에서 떼어 놓습니다.
• ADC는 GitLab.com에서 사용할 수 없습니다.

전송에 지정하는 Google Cloud 프로젝트 ID는 그 전송이 접근할 수 있는 버킷을 제한하지 않습니다. 버킷 이름은 Cloud Storage에서 전역으로 고유하므로, ADC 전송은 서비스 계정이 액세스할 수 있고 이름이 gitlab-offline-transfer-로 시작하는 버킷이라면 어떤 Google Cloud 프로젝트에 있든 사용할 수 있습니다.

GitLab은 사용자가 전송을 만들 때 이 제한을 확인합니다. 이 설정을 끄면 사용자는 더 이상 ADC 전송을 만들 수 없지만, 이미 시작된 전송은 계속 실행됩니다.

오프라인 전송에 Application Default Credentials를 허용하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings 섹션을 확장합니다.
4. Allow Google Cloud Application Default Credentials for offline transfer로 스크롤합니다.
5. Enabled 체크박스를 선택합니다.
6. Save changes를 선택합니다.

같은 설정을 API에서도 allow_application_default_credentials_for_offline_transfer 속성으로 사용할 수 있습니다.

관리자 사일런트 익스포트 활성화#

히스토리

• GitLab 17.0에서 export_audit_events라는 기능 플래그와 함께 도입됐습니다. 기본적으로 비활성화됩니다.
• GitLab 17.1에서 일반적으로 사용 가능해졌습니다. 기능 플래그 export_audit_events가 제거됐습니다.
• GitLab 17.1에서 파일 익스포트 다운로드에 대해 도입됐습니다.

인스턴스 관리자가 감사 이벤트를 발생시키지 않고 프로젝트 또는 그룹 파일 익스포트를 트리거하거나 익스포트 파일을 다운로드하도록 관리자 사일런트 익스포트를 활성화합니다. 관리자가 아닌 사용자의 익스포트는 계속 감사 이벤트를 생성합니다.

관리자의 사일런트 프로젝트 및 그룹 파일 익스포트를 활성화하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택한 다음 Import and export settings를 확장합니다.
3. Silent exports by admins로 스크롤합니다.
4. Enabled 체크박스를 선택합니다.

관리자에게 기여 매핑 허용#

히스토리

• GitLab 17.5에서 importer_user_mapping이라는 기능 플래그와 함께 도입됐습니다. 기본적으로 비활성화됩니다.
• GitLab 17.7에서 GitLab.com과 GitLab Self-Managed에서 활성화됐습니다.
• GitLab 18.3에서 일반적으로 사용 가능해졌습니다. 기능 플래그 importer_user_mapping 이 제거됐습니다.

임포트된 사용자 기여를 관리자에게 매핑하도록 허용하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택한 다음 Import and export settings를 확장합니다.
3. Allow contribution mapping to administrators로 스크롤합니다.
4. Enabled 체크박스를 선택합니다.

관리자가 플레이스홀더 사용자를 재할당할 때 확인 건너뛰기#

히스토리

• GitLab 18.1에서 importer_user_mapping_allow_bypass_of_confirmation이라는 기능 플래그와 함께 도입됐습니다. 기본적으로 비활성화됩니다.
• GitLab 18.6에서 일반적으로 사용 가능해졌습니다. 기능 플래그 importer_user_mapping_allow_bypass_of_confirmation 이 제거됐습니다.

사전 요구 사항:

• GitLab 인스턴스에서 사용자 가장이 비활성화되어 있지 않은지 확인합니다.

관리자가 플레이스홀더 사용자를 재할당할 때 확인을 건너뛰려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. Skip confirmation when administrators reassign placeholder users에서 Enabled 체크박스를 선택합니다.

이 설정을 활성화하면 관리자는 다음 상태 중 하나인 봇이 아닌 사용자에게 기여와 멤버십을 재할당할 수 있습니다.

• active
• banned
• blocked
• blocked_pending_approval
• deactivated
• ldap_blocked

최대 익스포트 크기#

GitLab에서 익스포트의 최대 파일 크기를 수정하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택한 다음 Import and export settings를 확장합니다.
3. **Maximum export size (MiB)**의 값을 변경해 늘리거나 줄입니다.

최대 임포트 크기#

GitLab에서 임포트의 최대 파일 크기를 수정하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. **Maximum import size (MiB)**의 값을 변경해 늘리거나 줄입니다.

이 설정은 GitLab 익스포트 파일에서 임포트한 리포지터리에만 적용됩니다.

이 설정은 GitLab 자체가 적용하는 제한만 제어합니다. GitLab 앞단의 HTTP 프록시나 로드 밸런서는 각각 독립적인 요청 크기 제한을 적용하며, 그 제한은 별도로 구성해야 합니다.

GitLab.com의 리포지터리 크기 제한은 계정 및 제한 설정을 참고합니다.

임포트의 최대 원격 파일 크기#

기본적으로 외부 오브젝트 스토리지(예: AWS)에서 임포트할 때의 최대 원격 파일 크기는 10 GiB 입니다.

이 설정을 수정하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. **Maximum import remote file size (MiB)**에 값을 입력합니다. 파일 크기 제한을 두지 않으려면 0으로 설정합니다.

직접 전송 또는 오프라인 전송 임포트의 최대 다운로드 파일 크기#

기본적으로 직접 전송과 오프라인 전송으로 임포트할 때의 최대 다운로드 파일 크기는 5 GiB 입니다.

이 설정을 수정하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. **Maximum download file size (MiB)**에 값을 입력합니다. 파일 크기 제한을 두지 않으려면 0으로 설정합니다.

임포트된 아카이브의 최대 압축 해제 파일 크기#

파일 익스포트 또는 직접 전송으로 프로젝트를 임포트할 때 임포트된 아카이브의 최대 압축 해제 파일 크기를 지정할 수 있습니다. 기본값은 25 GiB 입니다.

압축된 파일을 임포트할 때 압축 해제 크기는 최대 압축 해제 파일 크기 제한을 초과할 수 없습니다. 압축 해제 크기가 구성된 제한을 초과하면 다음 오류가 반환됩니다.

Decompressed archive size validation failed.

이 설정을 수정하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. **Maximum decompressed file size for archives from imports (MiB)**에 다른 값을 설정합니다.

아카이브 파일 압축 해제 시간 초과#

프로젝트를 임포트할 때 임포트된 아카이브의 압축을 해제하는 최대 시간 초과를 지정할 수 있습니다. 기본값은 210 초입니다.

GitLab에서 임포트의 최대 압축 해제 파일 크기를 수정하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. **Timeout for decompressing archived files (seconds)**에 다른 값을 설정합니다.

인스턴스 전체의 최대 동시 import job 수#

히스토리

• GitLab 19.1에서 도입됐습니다.

모든 import job은 실행되는 동안 Sidekiq 스레드 하나를 점유합니다. 임포트를 조율하는 워커(파일 기반 프로젝트 및 그룹 임포트, 직접 전송, 그리고 GitHub, Bitbucket Cloud, Bitbucket Server 임포터의 stage job)는 오래 실행될 수 있어, 한 번에 너무 많이 실행되면 Sidekiq 스레드 풀 전체를 점유해 다른 백그라운드 작업을 막을 수 있습니다.

import_jobs_concurrency_limit 설정은 이렇게 오래 실행되는 job 이 동시에 몇 개까지 실행될 수 있는지 제한합니다. 이 제한은 공유되는 단일 총량이 아니라 워커 유형마다 독립적으로 적용됩니다. 워커 유형의 제한을 넘는 job은 그 유형의 실행 중인 job 이 끝날 때까지 대기합니다.

기본값은 워커 유형별 동시 job 100 개입니다. 변경하려면 import_jobs_concurrency_limit과 함께 /api/v4/application/settings로 API 요청을 보냅니다. 자세한 내용은 애플리케이션 설정 API를 참고합니다.

최대 동시 import job 수#

단일 프로젝트 임포트 안에서, 임포터가 동시에 예약하는 하위 job(예: 이슈 하나 또는 풀 리퀘스트 하나당 job 하나)의 개수를 제한할 수 있습니다. 단일 임포트가 동시에 예약하는 job 수를 제어하는 데 사용합니다. 적용 대상은 다음과 같습니다.

• GitHub 임포터
• Bitbucket Cloud 임포터
• Bitbucket Server 임포터

이는 import_jobs_concurrency_limit과 다릅니다. 그 설정은 인스턴스 전체에서 오래 실행되는 조율 워커와 stage 워커를 워커 유형마다 독립적으로 제한하고, 이 설정은 단일 임포트 내부의 짧게 끝나는 하위 job을 제한합니다. 하위 job은 빠르게 끝나므로 기본값이 훨씬 높습니다.

머지 리퀘스트를 임포트할 때는 job 제한이 적용되지 않습니다. 머지 리퀘스트에는 이미 하드코딩된 제한이 있어 서버 과부하를 방지합니다.

기본 job 제한은 다음과 같습니다.

• GitHub 임포터: 1000.
• Bitbucket Cloud 및 Bitbucket Server 임포터: 100. Bitbucket 임포터는 적절한 기본값이 아직 정해지지 않아 기본값이 낮습니다. 인스턴스 관리자는 더 높은 제한으로 실험해 보는 것이 좋습니다.

이 설정을 수정하려면 다음과 같이 합니다.

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. 원하는 임포터에 대해 Maximum number of simultaneous import jobs에 다른 값을 설정합니다.

최대 동시 배치 익스포트 job 수#

히스토리

• GitLab 17.6에서 도입됐습니다.

직접 전송 익스포트는 상당한 양의 리소스를 소비할 수 있습니다. 데이터베이스나 Sidekiq 프로세스를 모두 소진하지 않도록 관리자는 concurrent_relation_batch_export_limit 설정을 구성할 수 있습니다.

기본값은 job 8 개이며, 이는 최대 40 RPS 또는 사용자 2,000 명 규모의 참조 아키텍처에 해당합니다. PG::QueryCanceled: ERROR: canceling statement due to statement timeout 오류가 발생하거나 Sidekiq 메모리 제한으로 job 이 중단되면 이 수를 줄이는 편이 좋습니다. 리소스가 충분하다면 이 수를 늘려 더 많은 동시 익스포트 job을 처리할 수 있습니다.

이 설정을 수정하려면 concurrent_relation_batch_export_limit과 함께 /api/v4/application/settings로 API 요청을 보냅니다. 자세한 내용은 애플리케이션 설정 API를 참고합니다.

동시 프로젝트 파일 익스포트#

히스토리

• GitLab 19.4에서 limit_concurrent_project_exports라는 기능 플래그와 함께

프로젝트 파일 익스포트는 메모리와 디스크 공간이 제한된 Sidekiq 노드에서 실행되므로, 동시 익스포트가 너무 많으면 그 노드가 포화되어 인스턴스의 모든 익스포트가 지연될 수 있습니다. 동시에 실행되는 프로젝트 파일 익스포트 수를 제한하려면 관리자가 concurrent_relation_export_limit 설정을 구성할 수 있습니다.

기본값은 익스포트 25 개입니다. 제한에 도달한 상태에서 요청된 익스포트는 큐에 남아 있다가 실행 중인 익스포트가 끝나는 대로 요청된 순서로 시작됩니다.

이 설정을 수정하려면 concurrent_relation_export_limit과 함께 /api/v4/application/settings로 API 요청을 보냅니다. 자세한 내용은 애플리케이션 설정 API를 참고합니다.

익스포트 배치 크기#

히스토리

• GitLab 18.2에서 도입됐습니다.

메모리 사용량과 데이터베이스 부하를 더 관리하려면 relation_export_batch_size 설정으로 익스포트 작업 중 각 배치에서 처리하는 레코드 수를 제어합니다.

기본값은 배치당 레코드 50 개입니다. 이 설정을 수정하려면 relation_export_batch_size와 함께 /api/v4/application/settings로 API 요청을 보냅니다. 자세한 내용은 애플리케이션 설정 API를 참고합니다.

문제 해결#

오류: Help page documentation base url is blocked: execution expired#

임포트 소스 같은 애플리케이션 설정을 활성화하는 동안 Help page documentation base url is blocked: execution expired 오류가 발생할 수 있습니다. 이 오류를 우회하려면 다음과 같이 합니다.

1. docs.gitlab.com 또는 리디렉션 도움말 문서 페이지 URL을 허용 목록에 추가합니다.
2. Save Changes를 선택합니다.

관련 주제#

• GitLab으로 임포트 및 마이그레이션.
• 임포트를 위한 Sidekiq 구성.
• 여러 Sidekiq 프로세스 실행.
• 특정 job 클래스 처리.