직접 전송을 사용하여 그룹 및 프로젝트 마이그레이션

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

직접 전송을 사용하여 GitLab 그룹 및 프로젝트를 마이그레이션하려면 다음을 수행해야 합니다:

  1. 전제 조건을 충족하십시오.
  2. 소스 GitLab 인스턴스에 연결합니다.
  3. 마이그레이션할 그룹 및 프로젝트를 선택하고 마이그레이션을 시작합니다.
  4. 가져오기 결과를 검토합니다.

문제가 있는 경우 다음을 수행할 수 있습니다:

  1. 마이그레이션을 취소하거나 다시 시도합니다.
  2. 문제 해결 정보를 확인합니다.

전제 조건

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

직접 전송을 사용하여 마이그레이션하기 전에 아래의 전제 조건을 확인하십시오.

네트워크

  • 인스턴스 또는 GitLab.com 간의 네트워크 연결은 HTTPS를 지원해야 합니다.
  • 방화벽은 소스 및 대상 GitLab 인스턴스 간의 연결을 차단해서는 안 됩니다.

버전

성공적이고 성능이 우수한 마이그레이션의 가능성을 극대화하기 위해 다음을 권장합니다:

  • 관계의 배치 내보내기 및 가져오기를 활용하려면 소스 및 대상 인스턴스를 GitLab 16.8 이상으로 업데이트하십시오.
  • 가능한 한 최신 버전 간에 마이그레이션하십시오.
    소스 및 대상 인스턴스를 가능한 한 늦은 버전으로 업데이트하여 시간에 따른 버그 수정 및 개선을 활용하십시오.

우리는 GitLab 16.2를 실행하는 소스 인스턴스와 GitLab 16.8을 실행하는 대상 인스턴스 간의 마이그레이션을 성공적으로 테스트했습니다.

구성

  • 두 GitLab 인스턴스 모두에서 그룹 마이그레이션을 직접 전송을 통해 애플리케이션 설정에서 활성화해야 합니다.
    • 인스턴스 관리자에 의해 설정됩니다.
  • 소스 GitLab 인스턴스에 대한
    개인 액세스 토큰이 있어야 합니다:
    • GitLab 15.1 이후 소스 인스턴스의 경우 개인 액세스 토큰은 api 범위를 가져야 합니다.
    • GitLab 15.0 이전 소스 인스턴스의 경우 개인 액세스 토큰은 api와 read_repository 범위를 모두 가져야 합니다.
  • 마이그레이션할 소스 그룹의 경우 Owner 역할을 가져야 합니다.
  • 해당 네임스페이스에서 하위 그룹을 생성할 수 있는 역할이 있어야 합니다.
  • 객체 저장소에 저장된 항목을 가져오려면 다음 중 하나를 수행해야 합니다:
    • proxy_download 구성.
    • 대상 GitLab 인스턴스가 소스 GitLab 인스턴스의 객체 저장소에 접근할 수 있도록 합니다.
  • 소스 인스턴스 또는 그룹에 Default project creation protection이 No one으로 설정되어 있는 경우 프로젝트가 있는 그룹을 가져올 수 없습니다. 필요한 경우 이 설정은 다음과 같이 변경할 수 있습니다:

사용자 기여 및 회원 매핑

  • 직접 회원으로서의 공유 및 상속된 공유 멤버 매핑은 GitLab 16.3에서 도입되었습니다.
  • GitLab 16.11에서 도입된 공유 및 상속된 공유 멤버는 이미 가져온 그룹 또는 프로젝트의 공유 또는 상속된 공유 멤버인 경우 더 이상 직접 회원으로 매핑되지 않습니다.
  • 상속된 회원 매핑에 대한 전체 지원은 GitLab 17.1에서 도입되었습니다.

사용자는 마이그레이션 중에 생성되지 않습니다. 대신, 소스 인스턴스의 사용자 기여 및 회원은 대상 인스턴스의 사용자에 매핑됩니다. 사용자의 회원 매핑 유형은 소스 인스턴스의 회원 유형에 따라 다릅니다:

  • 직접 회원은 대상 인스턴스에서 직접 회원으로 매핑됩니다.
  • 상속된 회원은 대상 인스턴스에서 상속된 회원으로 매핑됩니다.
  • 공유 회원은 사용자가 이미 공유 회원인 경우를 제외하고 대상 인스턴스에서 직접 회원으로 매핑됩니다. 공유 회원 매핑에 대한 전체 지원은 이슈 458345에서 제안되었습니다.

inherited and shared 회원을 매핑할 때, 사용자가 대상 네임스페이스에서 더 높은 역할을 가진 기존 회원이 있는 경우, 해당 회원은 직접 회원으로 매핑됩니다. 이렇게 하면 회원이 권한이 상승하지 않도록 보장됩니다.

note
공유 회원 매핑에 영향을 미치는 알려진 이슈가 있습니다.

새로운 실험적 사용자 기여 및 회원 매핑 기능에 대한 내용은
사용자 기여 및 회원 매핑을 참조하십시오.

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

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

  1. 대상 GitLab 인스턴스에서 필요한 사용자를 생성합니다. API를 사용하여 사용자를 생성할 수 있는 것은 자가 관리 인스턴스만 가능하며, 이는 관리자 접근이 필요하기 때문입니다. GitLab.com 또는 자가 관리 GitLab 인스턴스로 마이그레이션할 때:

  2. 소스 GitLab 인스턴스에서 사용자의 공개 이메일이 대상 GitLab 인스턴스에서 확인된 이메일 주소와 일치하는지 확인합니다. 대부분 사용자는 이메일 주소를 확인하라는 이메일을 받습니다.

  3. 대상 인스턴스에 이미 사용자가 존재하고 SAML SSO for GitLab.com 그룹을 사용하는 경우, 모든 사용자는 자신의 SAML ID를 GitLab.com 계정에 연결해야 합니다.

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

소스 GitLab 인스턴스 연결하기

가져오고자 하는 그룹을 만들고 소스 GitLab 인스턴스를 연결합니다:

  1. 다음 중 하나를 생성합니다:
    • 새 그룹. 왼쪽 사이드바의 상단에서 새로 만들기 ( )를 선택하고 새 그룹을 선택합니다. 그런 다음 그룹 가져오기를 선택합니다.
    • 새 하위 그룹. 기존 그룹 페이지에서:
      • 새 하위 그룹을 선택합니다.
      • 왼쪽 사이드바의 상단에서 새로 만들기 ( )를 선택하고 새 하위 그룹을 선택합니다. 그런 다음 기존 그룹 가져오기 링크를 선택합니다.

  2. GitLab 인스턴스의 기본 URL을 입력합니다.

  3. 소스 GitLab 인스턴스의 개인 액세스 토큰을 입력합니다.

  4. 인스턴스 연결을 선택합니다.

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

  • GitLab 15.8에서 도입된, 프로젝트 유무에 따라 그룹을 가져오는 옵션.

소스 GitLab 인스턴스에 대한 접근 권한을 승인한 후, GitLab 그룹 가져오기 페이지로 리디렉션됩니다. 여기서 관리자로서 역할을 맡고 있는 연결된 소스 인스턴스의 최상위 그룹 목록을 확인할 수 있습니다.

  1. 기본적으로 제안된 그룹 네임스페이스는 소스 인스턴스에 존재하는 이름과 일치하지만, 권한에 따라 가져오기 전에 이러한 이름을 편집할 수 있습니다. 그룹 및 프로젝트 경로는 제한 사항을 준수해야 하며, 가져오기 실패를 방지하기 위해 필요 시 정규화됩니다.

  2. 가져오고자 하는 그룹 옆에서 다음 중 하나를 선택합니다:
    • 프로젝트 포함하여 가져오기. 이 옵션이 없는 경우 사전 요구 사항을 참조하세요.
    • 프로젝트 없이 가져오기.

  3. 상태 열에서 각 그룹의 가져오기 상태를 보여줍니다. 페이지를 열린 상태로 두면 실시간으로 업데이트됩니다.

  4. 그룹이 가져와지면 해당 GitLab 경로를 선택하여 GitLab URL을 엽니다.

경고:

프로젝트가 포함된 그룹을 가져오는 것은 베타입니다. 이 기능은 프로덕션 사용을 위해 준비되지 않았습니다.

그룹 가져오기 기록

  • 부분적으로 완료됨 상태는 GitLab 16.7에서 도입됨.

직접 전송을 통해 마이그레이션한 모든 그룹을 그룹 가져오기 기록 페이지에서 확인할 수 있습니다. 이 목록에는 다음이 포함됩니다:

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

그룹 가져오기 기록을 보려면:

  1. GitLab에 로그인합니다.

  2. 왼쪽 사이드바에서 맨 위에 있는 새로 만들기 ( ) 및 새 그룹을 선택합니다.

  3. 그룹 가져오기를 선택합니다.

  4. 오른쪽 상단에서 기록을 선택합니다.

  5. 특정 가져기에 오류가 있는 경우 오류 표시를 선택하여 세부정보를 확인합니다.

가져오기 결과 검토

  • GitLab 16.6에서 도입됨 bulk_import_details_page라는 플래그와 함께. 기본적으로 활성화됨.
  • GitLab 16.8에서 기능 플래그 bulk_import_details_page가 제거됨.
  • 부분적으로 완료된 가져기 및 완료된 가져기에 대한 세부정보가 추가됨 GitLab 16.9에서.
  • GitLab 17.0에서 도입됨, 디자인, 에픽, 이슈, 병합 요청, 노트(시스템 노트 및 댓글), 스니펫 및 사용자 프로필 활동이 가져왔음을 나타내는 가져온 배지.

가져기 결과를 검토하려면:

  1. 그룹 가져오기 기록 페이지로 이동합니다.

  2. 실패한 가져기의 세부정보를 보려면 실패 또는 부분적으로 완료됨 상태의 가져기에서 오류 표시 링크를 선택합니다.

  3. 가져기가 부분적으로 완료됨 또는 완전 상태인 경우, 어떤 항목이 가져와졌고 어떤 항목이 가져와지지 않았는지 보려면 세부정보 보기를 선택합니다.

항목이 GitLab UI에서 가져온 배지를 볼 때 해당 항목이 가져와졌다는 것을 확인할 수 있습니다.

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

필요한 경우 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 또는 GitLab REST API를 사용하세요.
  • 특정 하위 그룹 또는 프로젝트의 경우, GitLab REST API를 사용하세요.