파일 내보내기를 사용하여 프로젝트 및 그룹을 마이그레이션하기
직접 전송을 사용하여 그룹 및 프로젝트를 마이그레이션하는 것이 권장됩니다. 그러나 일부 상황에서는 파일 내보내기를 사용하여 그룹 및 프로젝트를 마이그레이션해야 할 수 있습니다.
내보내기 파일을 업로드하여 프로젝트 마이그레이션하기
Self-managed GitLab 인스턴스 또는 GitLab.com의 기존 프로젝트는 파일로 내보내어 다른 GitLab 인스턴스로 가져올 수 있습니다.
사용자 기여 보존하기
사용자 기여를 보존하기 위한 요구 사항은 GitLab.com 또는 GitLab Self-managed 인스턴스로 마이그레이션하는지에 따라 다릅니다.
GitLab Self-managed에서 GitLab.com으로 마이그레이션하는 경우
파일 내보내기를 사용하여 프로젝트를 마이그레이션할 때 사용자 기여를 올바르게 매핑하려면 관리자 액세스 토큰이 필요합니다.
그러므로 사용자 기여는 GitLab.com으로부터 Self-managed 인스턴스로 파일 내보내기를 가져올 때 올바르게 매핑되지 않습니다. 대신, 모든 GitLab 사용자 관련성(예: 코멘트 작성자)이 프로젝트를 가져온 사용자로 변경됩니다. 기여 이력을 보존하려면 다음 중 하나를 수행하세요:
- 직접 전송을 사용하여 마이그레이션합니다.
- 전문 서비스를 이용해 보세요. 자세한 정보는 전문 서비스 풀 카달로그를 참조하십시오.
GitLab Self-managed로 마이그레이션하는 경우
GitLab이 사용자와 그들의 기여를 올바르게 매핑하도록 하려면:
- 프로젝트의 최상위 그룹 소유자는 모든 멤버(직접 및 상속)의 정보를 내보내어 포함시킬 수 있도록 프로젝트를 내보내어야 합니다. 프로젝트 유지자 및 소유자는 프로젝트 내보내기를 시작할 수 있지만, 그 후에는 직접 멤버만 내보내집니다.
- 관리자가 가져오기를 수행하여야 합니다.
- 필요한 사용자는 대상 GitLab 인스턴스에 존재하여야 합니다. 관리자는 Rails 콘솔에서 대량으로 확인된 사용자를 생성하거나 UI에서 한 명씩 생성할 수 있습니다.
- 사용자는 소스 GitLab 인스턴스에서 그들의 주요 이메일 주소와 일치하는 공개 이메일을 설정해야 합니다. 프로젝트 내보내기 파일을 수정하여 사용자의 공개 이메일을 매뉴얼으로 추가할 수도 있습니다.
기존 사용자의 이메일이 가져온 사용자의 이메일과 일치하는 경우, 해당 사용자는 가져온 프로젝트의 직접 멤버로 추가됩니다.
이전 조건 중 하나라도 충족되지 않으면 사용자 기여가 올바르게 매핑되지 않습니다. 대신에, 모든 GitLab 사용자 관련성이 가져오기를 수행한 사용자로 변경됩니다. 이 사용자는 다른 사용자가 생성한 Merge Request의 작성자가 됩니다. 원본 작성자를 언급하는 보조 코멘트는 다음과 같습니다:
- 코멘트, Merge Request 승인, 연결된 작업 및 항목이 추가됩니다.
- Merge Request 또는 이슈 생성자, 추가 또는 제거된 라벨, Merge한 사용자 정보는 추가되지 않습니다.
프로젝트 내보내기 파일 편집
내보내기 파일에서 데이터를 추가하거나 제거할 수 있습니다. 예를 들어, 다음 작업을 수행할 수 있습니다:
-
project_members.ndjson파일에 매뉴얼으로 사용자 공개 이메일을 추가합니다. -
ci_pipelines.ndjson파일에서 줄을 제거하여 CI 파이프라인을 정리합니다.
프로젝트 내보내기 파일을 편집하려면:
- 내보낸
.tar.gz파일을 압축 해제합니다. - 적절한 파일을 편집합니다. 예를 들어,
tree/project/project_members.ndjson파일입니다. - 파일을
.tar.gz파일로 다시 압축합니다.
또한 project_members.ndjson 파일을 확인하여 모든 멤버가 내보내졌는지 확인할 수 있습니다.
호환성
- JSON 형식의 프로젝트 파일 내보내기 지원이 제거됨 GitLab 15.11에서.
프로젝트 파일 내보내기는 NDJSON 형식으로 이루어져 있습니다.
최대 두 마이너 버전 이전의 GitLab 버전에서 내보낸 프로젝트 파일을 가져올 수 있습니다.
예를 들어:
| 대상 버전 | 호환되는 소스 버전 |
|---|---|
| 13.0 | 13.0, 12.10, 12.9 |
| 13.1 | 13.1, 13.0, 12.10 |
가져오기 원본으로 파일 내보내기 구성하기
파일 내보내기를 사용하여 Self-managed GitLab 인스턴스에서 프로젝트를 마이그레이션하려면 GitLab 관리자는 다음을 수행해야 합니다:
- 소스 인스턴스에서 파일 내보내기 활성화를 설정합니다.
- 대상 인스턴스에서 가져오기 원본으로 파일 내보내기를 활성화합니다. GitLab.com에서는 파일 내보내기가 이미 가져오기 원본으로 활성화되어 있습니다.
대상 인스턴스에서 가져오기 원본으로 파일 내보내기를 활성화하려면:
- 왼쪽 사이드바에서 하단에 있는 관리 영역을 선택합니다.
- 설정 > 일반을 선택합니다.
- 가져오기 및 내보내기 설정을 확장합니다.
- 가져오기 원본으로 이동합니다.
- GitLab 내보내기 확인란을 선택합니다.
CE 및 EE 간
커뮤니티 에디션에서 엔터프라이즈 에디션으로 프로젝트를 내보낼 수 있으며, 호환성이 충족된다면 그 반대도 가능합니다.
엔터프라이즈 에디션에서 커뮤니티 에디션으로 프로젝트를 내보내는 경우, 엔터프라이즈 에디션에만 유지되는 데이터가 손실될 수 있습니다. 자세한 정보는 EE에서 CE로 다운그레이드를 참조하십시오.
프로젝트 및 해당 데이터 내보내기
프로젝트를 가져오려면 먼저 내보내야 합니다.
전제 조건:
- 내보내는 항목 디렉터리을 검토하세요. 모든 항목이 내보내지는 않습니다.
- 프로젝트에 최소한 유지자 역할이 있어야 합니다.
프로젝트와 해당 데이터를 내보내려면 다음 단계를 따릅니다:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > 일반을 선택합니다.
- 고급을 확장합니다.
- 프로젝트 내보내기를 선택합니다.
- 내보내기가 생성된 후, 다음을 수행할 수 있습니다:
- 받은 이메일에 포함된 링크를 따릅니다.
- 프로젝트 설정 페이지를 새로고침하고 프로젝트 내보내기 영역에서 내보내기 다운로드를 선택합니다.
내보내기는 구성된 shared_path(임시 공유 디렉터리)에 생성되고, 이후에 구성된 uploads_directory로 이동합니다. 24시간마다 작업자가 이러한 내보내기 파일을 삭제합니다.
내보낸 프로젝트 항목
내보낸 프로젝트 항목은 사용 중인 GitLab 버전에 따라 다릅니다. 특정 프로젝트 항목이 내보내졌는지 확인하려면 다음을 수행하세요.
-
exporters배열을 확인합니다. - 프로젝트용
project/import_export.yml파일을 확인합니다. GitLab 버전에 따라 해당 프로젝트의 파일을 확인하세요. 예를 들어, GitLab 16.8용 https://gitlab.com/gitlab-org/gitlab/-/blob/16-8-stable-ee/lib/gitlab/import_export/project/import_export.yml를 확인하세요.
간략히, 내보내지는 항목은 다음과 같습니다.
- 프로젝트 및 위키 리포지터리
- 프로젝트 업로드
- 통합을 제외한 프로젝트 구성
- 이슈
- Merge Request
- 커밋 코멘트 (GitLab 15.10에서 도입됨)
- 라벨
- 마일스톤
- 코드 스니펫
- 릴리스
- 시간 추적 및 기타 프로젝트 항목
- 디자인 관리 파일 및 데이터
- LFS 객체
- 이슈 보드
- CI/CD 파이프라인 및 파이프라인 스케줄
- 보호된 브랜치 및 태그
- 푸시 규칙
- 이모지 반응
- 프로젝트 및 상속된 그룹 구성원(내보낸 프로젝트의 그룹에서 유지자 역할을 하거나 관리자인 경우)
내보내지 않는 프로젝트 항목
내보내지 않는 항목은 다음과 같습니다.
- 하위 파이프라인 기록
- 파이프라인 트리거
- 빌드 추적 및 아티팩트
- 패키지 및 컨테이너 레지스트리 이미지
- CI/CD 변수
- 웹훅
- 암호화된 토큰
- 필요한 승인 수 (이슈 참조)
- 리포지터리 크기 제한
- 보호된 브랜치로 푸시할 수 있는 배포 키
- 보안 파일
- Git 관련 이벤트의 활동 로그(예: 푸시 및 태그 생성) (이슈 참조)
- 프로젝트와 관련된 보안 정책
- 이슈와 연결된 링크 항목
- 관련 Merge Request에 대한 링크
파일 내보내기를 사용하여 프로젝트를 마이그레이션하면, 그룹 및 인스턴스에서 템플릿을 사용하여 프로젝트를 생성하는 것과 동일한 내보내고 가져오기 메커니즘을 사용합니다. 따라서, 내보내는 항목 디렉터리은 동일합니다.
프로젝트 및 해당 데이터 가져오기
프로젝트 및 해당 데이터를 가져올 수 있습니다. 가져올 수 있는 데이터 양은 최대 가져오기 파일 크기에 따라 달라집니다.
- GitLab Self-managed 인스턴스의 경우, Self-managed 인스턴스의 관리자는 최대 가져오기 파일 크기를 설정할 수 있습니다.
- GitLab.com의 경우, 해당 값은 5GB로 설정됩니다.
선행 조건
- GitLab 16.0에 소개되었으며 GitLab 15.11.1 및 GitLab 15.10.5로 backport된 개선 사항.
- 프로젝트와 해당 데이터를 내보내야 합니다.
- GitLab 버전을 비교하고 내보낸 GitLab 버전과 동일하거나 그 후의 GitLab 버전으로 가져오는지 확인하세요.
- 잠재적인 문제에 대해 호환성을 확인하세요.
- 마이그레이션할 대상 그룹에서 적어도 유지자 역할이 필요합니다.
프로젝트 가져오기
프로젝트를 가져오려면 다음을 수행하세요.
- 왼쪽 사이드바에서 상단에 새로 만들기 () 및 새 프로젝트/리포지터리를 선택합니다.
- 프로젝트 가져오기를 선택합니다.
- 프로젝트 가져오기에서 GitLab 내보내기를 선택합니다.
- 프로젝트 이름 및 URL을 입력한 다음 이전에 내보낸 파일을 선택합니다.
- 프로젝트 가져오기를 선택합니다.
API를 사용하여 가져오기 상태를 조회할 수 있습니다. 조회 결과로 가져오기 오류 또는 예외가 반환될 수 있습니다.
가져온 항목의 변경 사항
내보낸 항목은 다음과 같은 변경 사항이 적용된 채로 가져와집니다.
- 유지자 역할을 갖는 프로젝트 구성원이 유지자 역할로 가져와집니다.
- 가져온 프로젝트에 fork에서 유래한 Merge Request이 있는 경우, 이러한 Merge Request과 연관된 새 브랜치가 프로젝트에 생성됩니다. 따라서, 새 프로젝트의 브랜치 수는 소스 프로젝트보다 많을 수 있습니다.
-
내부가시성 수준이 제한된 경우, 모든 가져온 프로젝트에비공개가시성이 부여됩니다.
배포 키가 가져와지지 않습니다. 배포 키를 사용하려면 가져온 프로젝트에서 활성화하고 보호된 브랜치를 업데이트해야 합니다.
대규모 프로젝트 가져오기
대규모 프로젝트를 가져오려면 Rake 작업을 사용하는 것을 고려해보세요.
최대 가져오기 파일 크기 설정
관리자는 최대 가져오기 파일 크기를 두 가지 방법 중 하나로 설정할 수 있습니다:
-
Application settings API의
max_import_size옵션 사용 - Admin Area UI에서 설정
기본값은 0 (무제한)입니다.
요청 속도 제한
남용을 방지하기 위해 기본적으로 사용자의 요청은 다음과 같이 속도 제한이 적용됩니다:
| 요청 유형 | 제한 |
|---|---|
| 내보내기 | 분당 6개 프로젝트 |
| 내보내기 다운로드 | 그룹당 분당 1회 다운로드 |
| 가져오기 | 분당 6개 프로젝트 |
Deprecated 방식으로 그룹 이전하기
- GitLab 14.6에서 Deprecated.
전제 조건:
- 마이그레이션할 그룹에 대한 소유자 권한.
파일 내보내기를 사용하여 다음을 수행할 수 있습니다:
- 모든 그룹을 파일로 내보내고 해당 파일을 다른 GitLab 인스턴스나 동일 인스턴스의 다른 위치로 업로드합니다.
- GitLab UI 또는 API를 사용합니다.
- 그룹마다 하나씩 마이그레이션하고, 각 그룹에 대해 프로젝트를 내보내고 가져옵니다.
관리자 액세스 토큰을 사용하여 가져오기를 수행하면 GitLab이 사용자 기여를 올바르게 매핑합니다. 그러나 GitLab.com으로부터 Self-managed 인스턴스로 가져올 때 사용자 기여를 올바르게 매핑하지 않습니다. Self-managed 인스턴스에서 GitLab.com으로 가져올 때 사용자 기여의 올바른 매핑은 전문 서비스 팀의 유료 참여로 보존할 수 있습니다.
추가 정보
- 내보낸 파일은 임시 디렉터리에 저장되어 특정 워커에 의해 24시간마다 삭제됩니다.
- 가져오기된 프로젝트 간의 그룹 수준 관계를 보존하려면 원하는 그룹 구조에 프로젝트를 가져오려면 먼저 그룹을 내보내고 가져와야 합니다.
- 가져온 그룹은
private가시성 수준이 부여되며, 상위 그룹으로 가져오는 경우 다른 제한이 없는 한 하위 그룹은 동일한 가시성 수준을 상속받습니다. - Community Edition에서 Enterprise Edition으로 그룹을 내보내기 및 그 반대도 가능합니다. Enterprise Edition에는 Community Edition에 없는 일부 그룹 데이터가 포함되어 있습니다. Enterprise Edition에서 그룹을 Community Edition으로 내보내는 경우 이러한 데이터가 손실될 수 있습니다. 자세한 내용은 EE에서 CE로 다운그레이드를 참조하세요.
최대 가져오기 파일 크기는 GitLab Self-managed 인스턴스 또는 GitLab.com으로 가져오는 경우에 따라 다릅니다:
- GitLab Self-managed 인스턴스로 가져오는 경우, 가져오기 파일의 크기에 상관없이 가져올 수 있습니다. 관리자는 이 동작을 다음 중 하나를 사용하여 변경할 수 있습니다:
-
Application settings API의
max_import_size옵션 - Admin Area의 설정
-
Application settings API의
- GitLab.com에서는 5 GB를 넘지 않는 가져오기 파일로 그룹을 가져올 수 있습니다.
호환성
- JSON 포맷 프로젝트 파일 내보내기 지원이 GitLab 15.8에서 제거.
그룹 파일 내보내기는 NDJSON 형식입니다.
GitLab에서 최대 마이너 버전 두 개 전까지의 버전에서 내보낸 그룹 파일을 가져올 수 있습니다.
예를 들어:
| 대상 버전 | 호환되는 소스 버전 |
|---|---|
| 13.0 | 13.0, 12.10, 12.9 |
| 13.1 | 13.1, 13.0, 12.10 |
내보내기되는 그룹 항목
그룹을 파일로 내보내거나 그룹 파일을 가져올 때 내보내고 가져오는 항목이 나열되어 있는 import_export.yml 파일이 있습니다. 목적지 GitLab 인스턴스에 가져올 수 있는 항목을 확인하려면 해당 GitLab 버전의 브랜치에서 이 파일을 확인하세요. 예를 들어, 16-8-stable-ee 브랜치의 import_export.yml.
내보내는 그룹 항목은 다음과 같습니다:
- 이정표
- 그룹 레이블(관련 레이블 우선 순위 없음)
- 보드 및 보드 디렉터리
- 뱃지
- 하위 그룹 (앞서 언급된 모든 데이터 포함)
- 이픽
- 이픽 리소스 상태 이벤트. GitLab 15.4에서 도입.
- 이벤트
- 위키
- 이터레이션 캐딘스. GitLab 15.4에서 도입.
내보내지 않는 그룹 항목
내보내지 않는 항목은 다음과 같습니다:
- 프로젝트
- 러너 토큰
- SAML 디스커버리 토큰
- 업로드
준비
- 가져올 그룹에서 구성원 디렉터리과 해당 그룹의 권한을 보존하려면 이러한 그룹의 사용자를 검토하세요. 원하는 그룹을 가져오기 전에 해당 사용자가 존재하는지 확인하세요.
- 사용자는 목적지 GitLab 인스턴스에서 확인된 기본 이메일과 일치하는 공개 이메일을 설정해야 합니다. 대부분의 사용자는 이메일 주소를 확인하라는 이메일을 받습니다.
그룹의 내보내기 활성화
전제 조건:
- 그룹에 대한 소유자 역할이 있어야 합니다.
그룹의 내보내기를 활성화하려면:
- 왼쪽 사이드바에서 맨 아래에서 관리 영역(Admin Area)을 선택합니다.
- 설정 > 일반(General)을 선택합니다.
- 가져오기 및 내보내기 설정(Import and export settings)을 확장합니다.
- 가져오기 소스(Import sources) 섹션에서 GitLab 내보내기 확인란을 선택합니다.
그룹 내보내기
전제 조건:
- 그룹에 대한 소유자 역할이 있어야 합니다.
그룹의 내용을 내보내려면:
- 왼쪽 사이드바에서 검색 또는 이동(Search or go to)을 선택하고 그룹을 찾습니다.
- 설정 > 일반(General)을 선택합니다.
- 고급(Advanced) 섹션에서 그룹 내보내기(Export group)를 선택합니다.
- 내보내기가 생성된 후에는 다음을 할 수 있습니다:
- 이메일에 포함된 링크를 따릅니다.
- 그룹 설정 페이지를 새로고침하고 프로젝트 내보내기(Export project) 영역에서 내보내기 다운로드(Download export)를 선택합니다.
그룹 가져오기
그룹을 가져오려면:
- 왼쪽 사이드바에서 맨 위에서 새로 만들기(Create new)()를 선택하고 새 그룹(New group)을 선택합니다.
- 그룹 가져오기(Import group)를 선택합니다.
- 파일에서 그룹 가져오기(Import group from file) 섹션에서 그룹 이름을 입력하고 관련 그룹 URL을 수락하거나 수정합니다.
- 파일 선택(Choose file)을 선택합니다.
- 가져올 GitLab 내보내기 파일을 선택합니다.
- 가져오기를 시작하려면 가져오기(Import)을 선택합니다.
요금 제한
남용을 방지하기 위해 사용자는 기본적으로 다음과 같은 요금 제한이 적용됩니다:
| 요청 유형 | 제한 |
|---|---|
| 내보내기 | 분당 6개 그룹 |
| 내보내기 다운로드 | 그룹당 분당 1회 다운로드 |
| 가져오기 | 분당 6개 그룹 |
도움말