• 특정 프로젝트 마이그레이션
• 알려진 문제
• 마이그레이션 기간 추정
• 마이그레이션 기간 단축
  • 대상 인스턴스에 Sidekiq 워커 추가
  • 대형 프로젝트 분산 또는 별도의 마이그레이션 시작
• 제한 사항
• 가시성 규칙
• 직접 전송에 의한 마이그레이션 프로세스

직접 전송을 사용하여 GitLab 마이그레이션

• GitLab.com에서 활성화됨 - GitLab 15.6에서.
• GitLab 15.8에서 새 애플리케이션 설정 bulk_import_enabled 도입. bulk_import 기능 플래그가 제거되었습니다.
• bulk_import_projects 기능 플래그가 GitLab 15.10에서 제거되었습니다.

당신은 GitLab 그룹을 마이그레이션할 수 있습니다:

• Self-managed GitLab에서 GitLab.com으로.
• GitLab.com에서 self-managed GitLab로.
• 한 self-managed GitLab 인스턴스에서 다른 인스턴스로.
• 같은 GitLab 인스턴스 내의 그룹 간.

경고: 직접 전송을 사용하여 GitLab 그룹 및 프로젝트를 마이그레이션하는 것이 현재 사용 불가능합니다. 해결까지 예상 시간이 없습니다. 자세한 정보는 지원팀에 문의하십시오.

직접 전송을 통한 마이그레이션은 그룹의 새 복사본을 생성합니다. 그룹을 복사하는 대신 이동하려면 그룹을 전송해야합니다(그룹이 동일한 GitLab 인스턴스 내에 있는 경우). 이동하는 것이 더 빠르고 보다 완전한 옵션입니다.

다음 두 가지 방법으로 그룹을 마이그레이션할 수 있습니다:

• 직접 전송(권장).
• 내보내기 파일을 업로드함으로써.

GitLab.com에서 self-managed GitLab으로 마이그레이션하는 경우, 관리자는 self-managed GitLab 인스턴스에서 사용자를 생성할 수 있습니다.

self-managed GitLab에서는 기본적으로 그룹 항목을 마이그레이션할 수 없습니다. 기능을 표시하려면 관리자가 애플리케이션 설정에서 활성화해야합니다.

직접 전송을 통한 그룹 마이그레이션은 그룹을 한 곳에서 다른 곳으로 복사합니다. 다음을 수행할 수 있습니다:

• 한 번에 많은 그룹 복사.
• GitLab UI에서 상위 그룹을 복사하여:
  • 다른 상위 그룹.
  • 기존 상위 그룹의 하위 그룹.
  • GitLab.com을 포함한 다른 GitLab 인스턴스.
• API에서 상위 그룹 및 하위 그룹을 이러한 위치로 복사.
• 프로젝트와 함께 그룹 복사(베타 리소스 및 프로덕션에서 사용할 준비가 안 된 것). 프로젝트와 함께 그룹 복사는 다음을 사용할 수 있습니다:
  • GitLab.com에서 기본적으로.

모든 그룹 및 프로젝트 리소스가 복사되지는 않습니다. 복사된 리소스 목록은 아래와 같습니다:

• 마이그레이션된 그룹 항목.
• 마이그레이션된 프로젝트 항목.

경고: 프로젝트가 있는 그룹을 가져오는 것은 베타입니다. 이 기능은 아직 프로덕션에서 사용할 준비가 되지 않았습니다.

직접 전송을 통해 그룹을 마이그레이션하는 것에 관한 피드백을 남기시기를 피드백 이슈로 초대합니다.

특정 프로젝트 마이그레이션

GitLab UI에서 직접 전송을 사용하여 그룹을 마이그레이션하면 그룹의 모든 프로젝트가 마이그레이션됩니다. 특정 프로젝트만 이동하려면 API를 사용해야합니다.

알려진 문제

• 이슈 406685 때문에 파일 이름이 255자를 초과하는 파일은 마이그레이션되지 않습니다.
• GitLab 16.1 이전 버전에서, 예약된 스캔 실행 정책과 함께 직접 전송을 사용해서는 이용하지 않아야합니다.
• 다른 알려진 문제 목록은 에픽 6629을 참조하십시오.
• GitLab 16.9 이전 버전에서, 이슈 438422로 인해 DiffNote::NoteDiffFileCreationError 오류가 발생할 수 있습니다. 이 오류가 발생하면 병합 요청의 diff에서 diff가 누락되지만 노트와 병합 요청은 여전히 가져오게 됩니다.
• 원본 인스턴스에서 매핑된 공유 멤버는 해당 멤버쉽이 이미 대상에 존재하지 않는 한 대상의 직접 멤버로 매핑됩니다. 이는 소스 상위 그룹이 필요한 공유 멤버십 계층 구조 세부 정보를 포함하고 있더라도 소스 인스턴스의 상위 그룹을 대상 인스턴스의 상위 그룹으로 가져올 때 항상 프로젝트에서 직접 멤버쉽으로 매핑된다는 것을 의미합니다. 공유 멤버쉽의 전체 매핑 지원은 이슈 458345에서 제안되었습니다.
• GitLab 17.0, 17.1 및 17.2에서 가져오기된 에픽 및 작업 항목은 원래 작성자 대신 가져오는 사용자로 매핑됩니다.

마이그레이션 기간 추정

직접 전송을 통한 마이그레이션의 기간을 추정하는 것은 어렵습니다. 다음 요소가 마이그레이션 기간에 영향을 미칩니다:

• 소스 및 대상 GitLab 인스턴스에서 사용 가능한 하드웨어 및 데이터베이스 리소스. 소스 및 대상 인스턴스에서 더 많은 리소스가 사용 가능하면:
  • 소스 인스턴스는 API 요청을 수신하고 엔티티를 추출하며 내보내는 데 더 많은 시간이 걸립니다.
  • 대상 인스턴스는 작업을 실행하고 데이터베이스에 엔티티를 작성합니다.
• 내보낼 데이터의 복잡성과 크기. 예를 들어, 1000개의 병합 요청이 있는 두 가지 다른 프로젝트를 마이그레이션하려고 한다고 상상해보십시오. 두 프로젝트가 병합 요청에 첨부 파일, 댓글 및 기타 항목이 훨씬 더 있는 경우 하나의 프로젝트가 더 오래 마이그레이션 될 수 있습니다. 따라서 프로젝트의 병합 요청 수는 프로젝트가 마이그레이션하는 데 얼마나 오래 걸릴지를 예측하는 요측변수가 됩니다.

신뢰할 수 있는 마이그레이션을 예측하는 정확한 공식은 없습니다. 그러나 각 파이프라인 워커의 평균 지속 시간은 프로젝트 관계를 가져오는동안 어느 정도의 시간이 걸릴지 아이디어를 얻을 수 있습니다:

마이그레이션 기간을 정확하게 예측하는 것은 어렵지만 다음과 같은 경험치를 보았습니다:

• 8시간이 걸린 100개의 프로젝트(19.9k 이슈, 83k 병합 요청, 100k+ 파이프라인) 마이그레이션.
• 34시간이 걸린 1926개의 프로젝트(22k 이슈, 160k 병합 요청, 110만개 이상 파이프라인) 마이그레이션.

대규모 프로젝트를 마이그레이션하고 마이그레이션 지속 시간이나 타임아웃 문제가 발생하는 경우 마이그레이션 기간 단축을 참조하십시오.

마이그레이션 기간 단축

직접 이전을 사용하는 마이그레이션 기간을 줄이기 위한 몇 가지 전략입니다.

대상 인스턴스에 Sidekiq 워커 추가

단일 직접 전송 마이그레이션은 5개의 엔터티(그룹 또는 프로젝트)를 한 번에 가져오며 대상 인스턴스에서 사용 가능한 워커의 수에 관계없이 실행됩니다. 따라서 대상 인스턴스에 더 많은 Sidekiq 워커 프로세스를 추가하면 각 엔터티를 가져오는 데 걸리는 시간을 줄여 마이그레이션을 가속화할 수 있습니다.

대상 인스턴스에 더 많은 Sidekiq 워커를 추가하기 위해 다음을 수행할 수 있습니다:

1. 라우팅 규칙 사용. 이 접근 방식은 직접 전송 작업에 전용 Sidekiq 워커를 생성합니다.
2. 여러 개의 Sidekiq 프로세스 시작. 이 접근 방식을 사용하면 GitLab의 모든 대기열이 추가 Sidekiq 워커 프로세스를 활용할 수 있습니다.

라우팅 규칙을 사용하는 예시는 아래와 같습니다. 이 예시:

• 대상 인스턴스의 /etc/gitlab/gitlab.rb 파일에 추가할 수 있으며, 이후 재구성을 적용하기 위해 필요합니다.
• 네 개의 Sidekiq 워커 프로세스를 생성합니다. 이 중 세 개의 프로세스는 직접 전송 가져오기 대기열에 전용으로 사용되며, 마지막 프로세스는 모든 다른 대기열에 사용됩니다.
• CPU 코어에 할당하려는 수보다 많지 않게, 최대치로 프로세스 수를 설정해야 합니다. Sidekiq 워커 프로세스는 하나 이상의 CPU 코어를 사용하지 않습니다.

sidekiq['routing_rules'] = [
  ['feature_category=importers', 'importers'],
  ['*', 'default']
]

sidekiq['queue_groups'] = [
  # 가져오기 전용으로 두 개의 프로세스 실행
  'importers',
  'importers',
  'importers',

  # 기본 및 메일러 대기열에 대해 하나의 '캐치올' 프로세스 실행
  'default,mailers'
]

GitLab 16.11 이전을 사용하는 경우, 명시적으로 어떠한 대기열 선택기도 비활성화해야 합니다:

sidekiq['queue_selector'] = false

목적 인스턴스에서 워커 수를 증가시키면, 출처 인스턴스 하드웨어 리소스가 포화될 때까지 마이그레이션 기간을 줄이는 데 도움이 됩니다. 기본적으로 GitLab 16.8부터 이용 가능한 배치에서 관계를 내보내고 가져오는 것은 목적 인스턴스에서 충분한 워커를 사용하는 것을 더욱 유용하게 만듭니다.

대형 프로젝트 분산 또는 별도의 마이그레이션 시작

소스 인스턴스의 워커 수는 병렬로 5개의 동시 엔터티를 내보내기에 충분해야 합니다(각 실행되는 가져오기에 대해). 그렇지 않으면 대상이 내보낸 데이터의 사용 가능 여부를 기다리는 동안 지연 및 잠재적인 타임아웃이 발생할 수 있습니다.

서로 다른 그룹에 프로젝트를 분산시키면 타임아웃을 피하는 데 도움이 됩니다. 동일 그룹에 큰 프로젝트가 여러 개 있다면 다음을 수행할 수 있습니다:

1. 큰 프로젝트를 다른 그룹이나 하위 그룹으로 이동합니다.
2. 각 그룹 및 하위 그룹에 별도의 마이그레이션을 시작합니다.

GitLab UI는 최상위 그룹만 이전할 수 있습니다. API를 사용하면 하위 그룹도 마이그레이션할 수 있습니다.

제한 사항

• GitLab 16.7에서 제거된 마이그레이션에 대한 8시간 시간 제한.

직접 전송에 의한 마이그레이션에 하드코딩된 제한 사항이 적용됩니다.

구성 가능한 제한도 있습니다.

GitLab 16.3 이상에서 다음 이전에 하드코딩된 설정이 구성 가능하게 되었습니다:

• 소스 인스턴스에서 다운로드할 수 있는 최대 관계 크기 (5 GiB로 설정됨).
• 압축 해제된 아카이브의 최대 크기 (10 GiB로 설정됨).

이러한 API를 사용하여 최대 관계 크기 제한을 테스트할 수 있습니다:

• 그룹 관계 내보내기 API.
• 프로젝트 관계 내보내기 API

어느 API가 최대 관계 크기 제한보다 큰 파일을 생성하면, 직접 전송에 의한 그룹 마이그레이션이 실패합니다.

가시성 규칙

마이그레이션 후:

• 비공개 그룹 및 프로젝트는 비공개 상태를 유지합니다.
• 내부 그룹 및 프로젝트:
  • 내부 그룹으로 복사되면 내부 상태를 유지합니다(내부 가시성이 제한될 경우, 그룹 및 프로젝트는 비공개가 됩니다).
  • 비공개 그룹으로 복사되면 비공개가 됩니다.
• 공개 그룹 및 프로젝트:
  • 공개 그룹으로 복사되면 공개 상태를 유지합니다(공개 가시성이 제한될 경우, 그룹 및 프로젝트는 내부로 됩니다).
  • 내부 그룹으로 복사되면 내부가 되며(내부 가시성이 제한될 경우, 그룹 및 프로젝트는 비공개가 됩니다).
  • 비공개 그룹으로 복사되면 비공개가 됩니다.

출처 인스턴스에서 대중으로부터 콘텐츠를 숨기기 위해 사설 네트워크를 사용한 경우, 대상 인스턴스에 비슷한 설정이나 비공개 그룹에 가져오도록 하십시오.

직접 전송에 의한 마이그레이션 프로세스

직접 전송을 사용하여 그룹 및 프로젝트를 마이그레이션하는 방법을 참조하십시오.