다이렉트 트랜스퍼를 사용하여 GitLab 그룹 및 프로젝트를 마이그레이션하려면:

1. 사전 요구사항을 충족하는지 확인합니다.
2. 사용자 기여 및 사용자 멤버십 매핑을 검토합니다.
3. 소스 GitLab 인스턴스에 연결합니다.
4. 가져올 그룹 및 프로젝트를 선택하고 마이그레이션을 시작합니다.
5. 임포트 결과 검토.

문제가 있는 경우:

1. 마이그레이션을 취소하거나 재시도합니다.
2. 문제 해결 문서를 참조합니다.

사전 요구사항#

다이렉트 트랜스퍼를 사용하여 마이그레이션하기 전에 다음 사전 요구사항을 확인하세요.

네트워크 및 스토리지 공간#

• 인스턴스 또는 GitLab.com 간의 네트워크 연결은 HTTPS를 지원해야 합니다.
• 방화벽은 소스와 대상 GitLab 인스턴스 간의 연결을 차단하지 않아야 합니다.
• 소스 및 대상 GitLab 인스턴스는 전송된 프로젝트와 그룹의 아카이브를 만들고 추출하기 위해 /tmp 디렉토리에 충분한 여유 공간이 있어야 합니다.

버전#

성공적이고 성능이 좋은 마이그레이션의 가능성을 극대화하려면:

• 소스 및 대상 인스턴스를 모두 GitLab 16.8 이상으로 업그레이드합니다. 자세한 내용은 에픽 9036을 참조하세요.
• 버그 수정 및 기타 개선을 위해 가능한 한 최신 버전 간에 마이그레이션합니다.

소스 및 대상 인스턴스가 동일한 버전이 아닌 경우, 소스 인스턴스는 대상 인스턴스보다 두 개의 마이너 버전 이상 이전이어서는 안 됩니다. 이 요구사항은 GitLab.com에서 GitLab Dedicated로의 마이그레이션에는 적용되지 않습니다.

구성#

• Sidekiq가 제대로 구성되었는지 확인합니다.
• 두 GitLab 인스턴스 모두 인스턴스 관리자에 의해 애플리케이션 설정에서 다이렉트 트랜스퍼에 의한 그룹 마이그레이션이 활성화되어 있어야 합니다.
• 소스 GitLab 인스턴스에 대한 api 범위의 개인 접근 토큰이 있어야 합니다.
• 소스 및 대상 인스턴스에서 필요한 권한이 있어야 합니다. 다음에 대해:
  • 대부분의 사용자는 다음이 필요합니다:
    • 마이그레이션할 소스 그룹에서 Owner 권한.
    • 해당 네임스페이스에서 하위 그룹을 만들 수 있는 대상 네임스페이스의 권한.
  • 필요한 권한이 없는 두 인스턴스의 관리자는 대신 API를 사용하여 임포트를 시작할 수 있습니다.
• 프로젝트 스니펫을 가져오려면 스니펫이 소스 프로젝트에서 활성화되어 있는지 확인합니다.
• 오브젝트 스토리지에 저장된 항목을 가져오려면 다음 중 하나를 수행해야 합니다:
  • proxy_download 구성.
  • 대상 GitLab 인스턴스가 소스 GitLab 인스턴스의 오브젝트 스토리지에 접근할 수 있는지 확인합니다.
• 소스 인스턴스 또는 그룹의 프로젝트를 만드는 데 필요한 최소 기본 권한이 아무도 없음으로 설정된 경우 프로젝트가 있는 그룹을 가져올 수 없습니다. 필요한 경우 이 설정을 변경할 수 있습니다:
  • 전체 인스턴스에 대해.
  • 특정 그룹에 대해.
• 대상 네임스페이스 내에서 기존 마일스톤과 제목이 일치하는 가져온 마일스톤은 임포트 시 제목이 업데이트됩니다. 새 제목에는 고유한 접미사가 추가됩니다. 예를 들어 18.0은 18.0 (imported-3d-1770206299)가 됩니다. 이를 방지하려면 다이렉트 트랜스퍼를 시작하기 전에 소스 그룹 또는 프로젝트에서 마일스톤 이름을 변경합니다.

사용자 멤버십 매핑#

마이그레이션 중에는 사용자가 생성되지 않습니다. 대신 소스 인스턴스의 사용자 멤버십이 대상 인스턴스의 사용자에게 매핑됩니다. 사용자 멤버십에 대한 매핑 유형은 소스 인스턴스의 멤버십 유형에 따라 다릅니다:

• 임포트된 멤버십은 처음에 플레이스홀더 사용자에게 매핑됩니다.
• 직접 멤버십은 대상 인스턴스에서 직접 멤버십으로 매핑됩니다.
• 상속된 멤버십은 대상 인스턴스에서 상속된 멤버십으로 매핑됩니다.
• 공유 멤버십은 사용자에게 기존 공유 멤버십이 없는 한 대상 인스턴스에서 직접 멤버십으로 매핑됩니다. 공유 멤버십 매핑에 대한 전체 지원은 이슈 458345에서 제안됩니다.

GitLab 18.4 이상에서 프로젝트를 기존 그룹으로 직접 가져올 때 직접 멤버십을 만들면 이 그룹의 프로젝트에 사용자를 추가할 수 없음 설정이 적용됩니다.

상속 및 공유 멤버십을 매핑할 때, 사용자에게 대상 네임스페이스에서 매핑되는 것보다 더 높은 권한의 기존 멤버십이 있는 경우, 멤버십이 직접 멤버십으로 대신 매핑됩니다. 이는 멤버가 상승된 권한을 얻지 않도록 보장합니다.

대상 인스턴스에서 사용자 구성#

GitLab이 소스와 대상 인스턴스 간에 사용자 및 기여를 올바르게 매핑하도록 하려면:

1. 대상 GitLab 인스턴스에서 필요한 사용자를 만듭니다. API로 사용자를 만드는 것은 관리자 접근이 필요하기 때문에 GitLab Self-Managed 인스턴스에서만 가능합니다. GitLab.com 또는 GitLab Self-Managed로 마이그레이션할 때 다음을 수행할 수 있습니다:
   • 수동으로 사용자를 만듭니다.
   • 기존 SAML SSO 제공자를 설정하거나 사용하고 SCIM을 통해 지원되는 SAML SSO 그룹의 사용자 동기화를 활용합니다. 확인된 이메일 도메인으로 GitLab 사용자 계정 인증을 우회할 수 있습니다.
2. 사용자가 소스 GitLab 인스턴스에서 대상 GitLab 인스턴스의 확인된 이메일 주소와 일치하는 공개 이메일을 가지고 있는지 확인합니다. 대부분의 사용자는 이메일 주소를 확인하도록 요청하는 이메일을 받습니다.
3. 사용자가 대상 인스턴스에 이미 존재하고 GitLab.com 그룹에 대한 SAML SSO를 사용하는 경우, 모든 사용자는 SAML 아이덴티티를 GitLab.com 계정에 연결해야 합니다.

사용자의 공개 이메일 주소를 자동으로 설정하는 GitLab UI 또는 API 방법은 없습니다. 많은 사용자 계정에 공개 이메일 주소를 설정해야 하는 경우 잠재적인 해결 방법은 이슈 284495를 참조하세요.

소스 GitLab 인스턴스 연결#

대상 GitLab 인스턴스에서 가져올 그룹을 만들고 소스 GitLab 인스턴스를 연결합니다:

1. 다음 중 하나를 만듭니다:
   • 새 그룹. 오른쪽 상단에서 새로 만들기 (+)를 선택하고 새 그룹을 선택합니다. 그런 다음 그룹 가져오기를 선택합니다.
   • 새 하위 그룹. 기존 그룹의 페이지에서 다음 중 하나를 수행합니다:
     • 하위 그룹 만들기를 선택합니다.
     • 오른쪽 상단에서 새로 만들기 (+)를 선택하고 새 하위 그룹을 선택합니다. 그런 다음 기존 그룹 가져오기 링크를 선택합니다.
2. GitLab 인스턴스의 기본 URL을 입력합니다.
3. 소스 GitLab 인스턴스에 대한 개인 접근 토큰을 입력합니다.
4. 인스턴스 연결을 선택합니다.

가져올 그룹 및 프로젝트 선택#

소스 GitLab 인스턴스에 대한 접근 권한을 부여한 후 GitLab 그룹 임포터 페이지로 리디렉션됩니다. 여기서 Owner 권한이 있는 연결된 소스 인스턴스의 최상위 그룹 목록을 볼 수 있습니다.

소스 인스턴스의 모든 사용자 멤버십을 가져오지 않으려면 사용자 멤버십 가져오기 체크박스가 선택 해제되어 있는지 확인합니다. 예를 들어, 소스 인스턴스에 200명의 멤버가 있지만 50명의 멤버만 가져오려는 경우. 임포트가 완료된 후 그룹 및 프로젝트에 더 많은 멤버를 추가할 수 있습니다.

1. 기본적으로 제안된 그룹 네임스페이스는 소스 인스턴스에 있는 이름과 일치하지만 권한에 따라 가져오기 전에 이러한 이름을 편집하도록 선택할 수 있습니다. 그룹 및 프로젝트 경로는 이름 규칙을 준수해야 하며 임포트 실패를 방지하기 위해 필요한 경우 정규화됩니다.
2. 가져올 그룹 옆에서 다음 중 하나를 선택합니다:
   • 프로젝트와 함께 가져오기. 사용할 수 없는 경우 사전 요구사항을 참조하세요.
   • 프로젝트 없이 가져오기.
3. 상태 열은 각 그룹의 임포트 상태를 표시합니다. 페이지를 열어 두면 실시간으로 업데이트됩니다.
4. 그룹이 가져와진 후 GitLab 경로를 선택하여 GitLab URL을 엽니다.

임포트 결과 검토#

임포트 결과를 검토하려면:

1. 그룹 임포트 히스토리 페이지로 이동합니다.
2. 실패한 임포트의 세부 정보를 보려면 실패 또는 부분적으로 완료됨 상태의 임포트에서 오류 표시 링크를 선택합니다.
3. 임포트가 부분적으로 완료됨 또는 완료됨 상태인 경우 가져온 항목과 가져오지 않은 항목을 보려면 세부 정보 보기를 선택합니다.

GitLab UI의 일부 항목에서 임포트됨 배지를 볼 때 항목이 임포트되었음을 알 수 있습니다.

그룹 임포트 히스토리#

그룹 임포트 히스토리 페이지에 다이렉트 트랜스퍼로 마이그레이션한 모든 그룹을 볼 수 있습니다. 이 목록에는 다음이 포함됩니다:

• 소스 그룹의 경로.
• 대상 그룹의 경로.
• 각 임포트의 시작 날짜.
• 각 임포트의 상태.
• 오류가 발생한 경우 오류 세부 정보.

그룹 임포트 히스토리를 보려면:

1. GitLab에 로그인합니다.
2. 오른쪽 상단에서 새로 만들기 (+)를 선택하고 새 그룹을 선택합니다.
3. 그룹 가져오기를 선택합니다.
4. 오른쪽 상단에서 임포트 히스토리 보기를 선택합니다.
5. 특정 임포트에 오류가 있는 경우 오류 표시를 선택하여 세부 정보를 확인합니다.

실행 중인 마이그레이션 취소#

필요한 경우 REST API 또는 Rails 콘솔을 사용하여 실행 중인 마이그레이션을 취소할 수 있습니다.

REST API로 취소#

REST API로 실행 중인 마이그레이션을 취소하는 방법에 대한 정보는 마이그레이션 취소를 참조하세요.

Rails 콘솔로 취소#

Rails 콘솔로 실행 중인 마이그레이션을 취소하려면:

1. 대상 GitLab 인스턴스에서 Rails 콘솔 세션 시작.

2. 다음 명령을 실행하여 마지막 임포트를 찾습니다. USER_ID를 임포트를 시작한 사용자의 사용자 ID로 대체합니다:

   bulk_import = BulkImport.where(user_id: USER_ID).last
   

3. 다음 명령을 실행하여 임포트 및 이와 관련된 모든 항목을 실패 처리합니다:

   bulk_import.entities.each do |entity|
     entity.trackers.each do |tracker|
       tracker.batches.each(&:fail_op!)
     end
     entity.trackers.each(&:fail_op!)
     entity.fail_op!
   end
   bulk_import.fail_op!
   

bulk_import를 취소해도 소스 인스턴스에서 프로젝트를 내보내는 워커는 중지되지 않지만 대상 인스턴스가 다음을 수행하지 못하도록 합니다:

• 소스 인스턴스에 더 많은 프로젝트를 내보내도록 요청.
• 다양한 확인 및 정보를 위해 소스 인스턴스에 대한 기타 API 호출.

실패하거나 부분적으로 성공한 마이그레이션 재시도#

마이그레이션이 실패하거나 부분적으로 성공하지만 항목이 누락된 경우 마이그레이션을 재시도할 수 있습니다. 최상위 그룹 및 모든 하위 그룹과 프로젝트, 또는 특정 하위 그룹이나 프로젝트의 마이그레이션을 재시도하려면 GitLab UI 또는 다이렉트 트랜스퍼에 의한 그룹 및 프로젝트 마이그레이션 API를 사용합니다.