직접 전송으로 GitLab 그룹과 프로젝트를 마이그레이션하려면 다음 단계를 따릅니다.

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

문제가 발생하면 다음을 수행할 수 있습니다.

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

사전 요구사항#

직접 전송으로 마이그레이션하기 전에 다음 사전 요구사항을 확인합니다.

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

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

버전#

마이그레이션 성공률과 성능을 높이려면 다음을 권장합니다.

• 소스 인스턴스와 대상 인스턴스를 모두 GitLab 16.8 이상으로 업그레이드합니다. 자세한 내용은 에픽 9036을 참고합니다.
• 버그 수정과 그 밖의 개선 사항을 적용받도록 가능한 한 최신 버전 사이에서 마이그레이션합니다.

소스 인스턴스와 대상 인스턴스의 버전이 같지 않은 경우, 소스 인스턴스는 대상 인스턴스보다 마이너 버전 기준 두 단계를 초과해 낮아서는 안 됩니다. 이 요구 사항은 GitLab.com에서 GitLab Dedicated로 마이그레이션하는 경우에는 적용되지 않습니다.

구성#

• Sidekiq가 올바르게 구성되어 있는지 확인합니다.
• 두 GitLab 인스턴스 모두 인스턴스 관리자가 애플리케이션 설정에서 직접 전송을 통한 그룹 마이그레이션을 활성화해야 합니다.
• 소스 GitLab 인스턴스에 대해 api 스코프를 가진 개인 액세스 토큰이 있어야 합니다.
• 소스 인스턴스와 대상 인스턴스에서 필요한 권한이 있어야 합니다. 구체적으로는 다음과 같습니다.
  • 대부분의 사용자는 다음이 필요합니다.
    • 마이그레이션할 소스 그룹에 대한 Owner 권한.
    • 대상 네임스페이스에서 하위 그룹을 만들 수 있는 권한.
  • 필요한 권한이 없는 두 인스턴스의 관리자는 대신 API로 임포트를 시작할 수 있습니다.
• 프로젝트 스니펫을 가져오려면 소스 프로젝트에서 스니펫이 활성화되어 있어야 합니다.
• 오브젝트 스토리지에 저장된 항목을 가져오려면 다음 중 하나를 수행해야 합니다.
  • proxy_download를 구성합니다.
  • 대상 GitLab 인스턴스가 소스 GitLab 인스턴스의 오브젝트 스토리지에 접근할 수 있도록 합니다.
• 소스 인스턴스 또는 그룹의 Default minimum role required to create projects가 No one으로 설정되어 있으면 프로젝트를 포함한 그룹을 가져올 수 없습니다. 필요하다면 이 설정을 변경할 수 있습니다.
  • 인스턴스 전체 단위로 변경합니다.
  • 특정 그룹 단위로 변경합니다.
• 대상 네임스페이스 안에 기존 마일스톤과 제목이 일치하는 마일스톤을 가져오면 임포트 시 제목이 변경됩니다. 새 제목에는 고유한 접미사가 덧붙으며, 예를 들어 18.0은 18.0 (imported-3d-1770206299)가 됩니다. 이를 피하려면 직접 전송을 시작하기 전에 소스 그룹 또는 프로젝트에서 마일스톤 이름을 변경합니다.
• 다음 중 하나를 충족하는지 확인합니다.
  • 소스 네임스페이스와 대상 네임스페이스가 같은 조직에 속합니다.
  • 소스 네임스페이스와 대상 네임스페이스가 서로 다른 조직에 속하는 경우, 두 조직 모두 격리 상태로 표시되어 있지 않습니다.

사용자 멤버십 매핑#

마이그레이션 중에 사용자가 새로 생성되는 일은 없습니다. 대신 소스 인스턴스의 사용자 멤버십이 대상 인스턴스의 사용자에 매핑됩니다. 사용자 멤버십의 매핑 방식은 소스 인스턴스의 멤버십 유형에 따라 달라집니다.

• 가져온 멤버십은 처음에 플레이스홀더 사용자로 매핑됩니다.
• 직접 멤버십은 대상 인스턴스에서 직접 멤버십으로 매핑됩니다.
• 상속된 멤버십은 대상 인스턴스에서 상속된 멤버십으로 매핑됩니다.
• 공유 멤버십은 사용자에게 기존 공유 멤버십이 없는 한 대상 인스턴스에서 직접 멤버십으로 매핑됩니다. 공유 멤버십 매핑의 완전한 지원은 이슈 458345에 제안되어 있습니다.

GitLab 18.4 이상에서는 기존 그룹으로 프로젝트를 직접 가져오면서 직접 멤버십을 만들 때 Users cannot be added to projects in this group 설정이 적용됩니다.

상속 및 공유 멤버십을 매핑할 때, 사용자가 대상 네임스페이스에 매핑 대상보다 더 높은 권한의 기존 멤버십을 가지고 있으면 해당 멤버십은 직접 멤버십으로 매핑됩니다. 이렇게 하여 멤버가 상향된 권한을 갖지 않도록 합니다.

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

GitLab이 소스 인스턴스와 대상 인스턴스 사이에서 사용자와 기여를 올바르게 매핑하도록 하려면 다음 단계를 따릅니다.

1. 대상 GitLab 인스턴스에 필요한 사용자를 만듭니다. API로 사용자를 만들려면 관리자 액세스 권한이 필요하므로, API를 통한 사용자 생성은 GitLab Self-Managed 인스턴스에서만 가능합니다. GitLab.com 또는 GitLab Self-Managed로 마이그레이션할 때는 다음을 수행할 수 있습니다.
   • 사용자를 수동으로 만듭니다.
   • SAML SSO 공급자를 새로 설정하거나 기존 공급자를 사용하고, SCIM으로 지원되는 SAML SSO 그룹의 사용자 동기화를 활용합니다. 확인된 이메일 도메인으로 GitLab 사용자 계정 확인을 건너뛸 수도 있습니다.
2. 소스 GitLab 인스턴스에서 사용자의 공개 이메일이 대상 GitLab 인스턴스의 확인된 이메일 주소와 일치하는지 확인합니다. 대부분의 사용자는 이메일 주소 확인을 요청하는 메일을 받습니다.
3. 대상 인스턴스에 사용자가 이미 있고 GitLab.com 그룹의 SAML SSO를 사용한다면, 모든 사용자가 SAML ID를 GitLab.com 계정에 연결해야 합니다.

GitLab UI나 API에서 사용자의 공개 이메일 주소를 자동으로 설정하는 방법은 없습니다. 많은 사용자 계정에 공개 이메일 주소를 설정해야 한다면 이슈 284495에서 해결 방안을 참고합니다.

소스 GitLab 인스턴스 연결#

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

1. 다음 중 하나를 만듭니다.
   • 새 그룹. 오른쪽 위 모서리에서 Create new (+)와 New group을 선택합니다. 그런 다음 Import group을 선택합니다.
   • 새 하위 그룹. 기존 그룹 페이지에서 다음 중 하나를 수행합니다.
     • Create subgroup을 선택합니다.
     • 오른쪽 위 모서리에서 Create new (+)와 New subgroup을 선택합니다. 그런 다음 import an existing group 링크를 선택합니다.
2. GitLab 인스턴스의 기본 URL을 입력합니다.
3. 소스 GitLab 인스턴스의 개인 액세스 토큰을 입력합니다.
4. Connect instance를 선택합니다.

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

소스 GitLab 인스턴스에 대한 접근을 승인하면 GitLab 그룹 임포터 페이지로 이동합니다. 이 페이지에서 연결된 소스 인스턴스에서 Owner 권한을 가진 최상위 그룹 목록을 볼 수 있습니다.

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

1. 기본적으로 제안되는 그룹 네임스페이스는 소스 인스턴스의 이름과 동일하지만, 권한에 따라 임포트를 진행하기 전에 이 이름을 편집할 수 있습니다. 그룹과 프로젝트 경로는 명명 규칙을 따라야 하며, 임포트 실패를 막기 위해 필요한 경우 정규화됩니다.
2. 가져올 그룹 옆에서 다음 중 하나를 선택합니다.
   • Import with projects. 이 옵션을 사용할 수 없다면 사전 요구사항을 참고합니다.
   • Import without projects.
3. Status 열에는 각 그룹의 임포트 상태가 표시됩니다. 페이지를 열어 두면 실시간으로 갱신됩니다.
4. 그룹을 가져온 후 해당 GitLab 경로를 선택하면 그룹의 GitLab URL이 열립니다.

임포트 결과 검토#

임포트 결과를 검토하려면 다음 단계를 따릅니다.

1. 그룹 임포트 히스토리 페이지로 이동합니다.
2. 실패한 임포트의 상세 내용을 보려면 Failed 또는 Partially completed 상태인 임포트에서 Show errors 링크를 선택합니다.
3. 임포트가 Partially completed 또는 Complete 상태이면 View details를 선택해 어떤 항목이 임포트되었고 되지 않았는지 확인합니다.

GitLab UI의 일부 항목에 Imported 배지가 표시되는 것으로도 해당 항목이 임포트되었음을 확인할 수 있습니다.

그룹 임포트 히스토리#

직접 전송으로 마이그레이션한 그룹은 모두 그룹 임포트 히스토리 페이지에서 볼 수 있습니다. 이 목록에는 다음이 포함됩니다.

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

그룹 임포트 히스토리를 보려면 다음 단계를 따릅니다.

1. GitLab에 로그인합니다.
2. 오른쪽 위 모서리에서 Create new (+)와 New group을 선택합니다.
3. Import group을 선택합니다.
4. 오른쪽 위 모서리에서 View import history를 선택합니다.
5. 특정 임포트에 오류가 있으면 Show errors를 선택해 상세 내용을 확인합니다.

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

필요하다면 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를 사용합니다.