히스토리

• 대상 인스턴스에서 충돌을 방지하기 위한 마일스톤 제목 이름 변경이 GitLab 18.6.7 이상, 18.7.5 이상, 18.8.5 이상에서 도입되었습니다.

파일 내보내기는 오프라인 환경에서 작동하는 GitLab 데이터의 이식 가능한 패키지를 제공합니다. 이 마이그레이션 방법은 저장소, 이슈, 머지 리퀘스트, 댓글을 포함하여 대부분의 프로젝트 데이터를 보존합니다.

다음에 파일 내보내기를 사용하세요:

• 오프라인 환경 간 마이그레이션.
• 전체 그룹 구조 없이 특정 프로젝트 이동.

직접 전송은 대부분의 상황에서 권장되는 마이그레이션 방법입니다.

알려진 문제#

• 알려진 문제로 인해 PG::QueryCanceled: ERROR: canceling statement due to statement timeout 오류가 발생할 수 있습니다. 자세한 내용은 트러블슈팅 문서를 참조하세요.
• GitLab 17.0, 17.1, 17.2에서 가져온 에픽 및 작업 항목이 원래 작성자 대신 가져오는 사용자에게 매핑됩니다.
• 머지 리퀘스트의 경우 가져오기 또는 내보내기 중에 최신 diff만 보존됩니다. 프로젝트를 가져오거나 내보낸 후에는 최신 diff 버전과 머지 리퀘스트의 최신 파이프라인만 표시됩니다.
• 가져오기 시 대상 네임스페이스 내에서 기존 마일스톤과 일치하는 제목을 가진 가져온 마일스톤은 제목이 업데이트됩니다. 새 제목에는 고유한 접미사가 추가됩니다. 예: 18.0은 18.0 (imported-3d-1770206299)가 됩니다. 이를 방지하려면 직접 전송을 시작하기 전에 소스 그룹 또는 프로젝트에서 마일스톤 이름을 변경하세요.

내보내기 파일을 업로드하여 프로젝트 마이그레이션#

기존 프로젝트를 파일로 내보낸 다음 다른 GitLab 인스턴스로 가져올 수 있습니다.

사용자 기여 보존#

사용자 기여를 보존하기 위한 요구사항은 GitLab.com 또는 GitLab Self-Managed 인스턴스로 마이그레이션하는지에 따라 다릅니다.

GitLab Self-Managed에서 GitLab.com으로 마이그레이션할 때#

파일 내보내기를 사용하여 프로젝트를 마이그레이션할 때 사용자 기여가 올바르게 매핑되려면 관리자 접근 토큰이 필요합니다.

따라서 GitLab Self-Managed 인스턴스에서 GitLab.com으로 파일 내보내기를 가져올 때 사용자 기여는 올바르게 매핑되지 않습니다. 대신 모든 GitLab 사용자 연결(예: 댓글 작성자)이 프로젝트를 가져오는 사용자로 변경됩니다. 기여 히스토리를 보존하려면 다음 중 하나를 수행하세요:

• 직접 전송을 사용하여 마이그레이션.
• Professional Services 참여를 고려하세요. 자세한 내용은 Professional Services 카탈로그를 참조하세요.

GitLab Self-Managed로 마이그레이션할 때#

GitLab이 사용자와 기여를 올바르게 매핑하도록 하려면:

• 내보낸 파일에 프로젝트에 접근할 수 있는 모든 멤버(직접 및 상속)의 정보가 포함될 수 있도록 프로젝트 최상위 그룹의 소유자가 프로젝트를 내보내야 합니다. 프로젝트 메인테이너 및 소유자는 프로젝트 내보내기를 시작할 수 있습니다. 그러나 프로젝트의 직접 멤버만 내보내집니다.
• 관리자가 가져오기를 수행해야 합니다.
• 필요한 사용자가 대상 GitLab 인스턴스에 있어야 합니다. 관리자는 Rails 콘솔에서 일괄적으로 또는 UI에서 하나씩 확인된 사용자를 만들 수 있습니다.
• 사용자는 소스 GitLab 인스턴스에서 프로필에 공개 이메일을 설정해야 하며, 이 이메일은 대상 GitLab 인스턴스의 기본 이메일 주소와 일치해야 합니다. 프로젝트 내보내기 파일 편집으로 사용자의 공개 이메일을 수동으로 추가할 수도 있습니다.
• GitLab 18.4 이상에서 기존 그룹으로 프로젝트를 직접 가져올 때 직접 멤버십을 만들 때 이 그룹의 프로젝트에 사용자를 추가할 수 없음 설정이 적용됩니다.

기존 사용자의 이메일이 가져온 사용자의 이메일과 일치하면 해당 사용자는 가져온 프로젝트에 직접 멤버로 추가됩니다.

이전 조건 중 하나라도 충족되지 않으면 사용자 기여가 올바르게 매핑되지 않습니다. 대신 모든 GitLab 사용자 연결이 가져오기를 수행한 사용자로 변경됩니다. 해당 사용자는 다른 사용자가 만든 머지 리퀘스트의 작성자가 됩니다. 원래 작성자를 언급하는 보조 댓글이 추가됩니다:

• 댓글, 머지 리퀘스트 승인, 연결된 작업 및 항목에 추가됩니다.
• 머지 리퀘스트 또는 이슈 생성자, 추가 또는 제거된 레이블, 머지 정보에는 추가되지 않습니다.

프로젝트 내보내기 파일 편집#

내보내기 파일에서 데이터를 추가하거나 제거할 수 있습니다. 예를 들어 다음을 할 수 있습니다:

• project_members.ndjson 파일에 사용자의 공개 이메일을 수동으로 추가합니다.
• ci_pipelines.ndjson 파일에서 줄을 제거하여 CI 파이프라인을 잘라냅니다.

프로젝트 내보내기 파일을 편집하려면:

1. 내보낸 .tar.gz 파일을 추출합니다.
2. 적절한 파일을 편집합니다. 예: tree/project/project_members.ndjson.
3. 파일을 .tar.gz 파일로 다시 압축합니다.

project_members.ndjson 파일을 확인하여 모든 멤버가 내보내졌는지 확인할 수도 있습니다.

호환성#

히스토리

• JSON 형식의 프로젝트 파일 내보내기 지원이 GitLab 15.11에서 제거되었습니다.

프로젝트 파일 내보내기는 NDJSON 형식입니다.

GitLab의 최대 두 개의 마이너 버전 뒤에서 내보낸 프로젝트 파일 내보내기를 가져올 수 있습니다.

예를 들어:

가져오기 소스로 파일 내보내기 구성#

파일 내보내기를 사용하여 GitLab Self-Managed에서 프로젝트를 마이그레이션하려면 먼저 GitLab 관리자가 다음을 수행해야 합니다:

1. 소스 인스턴스에서 파일 내보내기 활성화.
2. 대상 인스턴스에 대한 가져오기 소스로 파일 내보내기 활성화. GitLab.com에서는 파일 내보내기가 이미 가져오기 소스로 활성화되어 있습니다.

대상 인스턴스에 대한 가져오기 소스로 파일 내보내기를 활성화하려면:

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
3. 가져오기 및 내보내기 설정을 확장합니다.
4. 가져오기 소스로 스크롤합니다.
5. GitLab 내보내기 체크박스를 선택합니다.

CE와 EE 간#

Community Edition에서 Enterprise Edition으로 또는 그 반대로 프로젝트를 내보낼 수 있으며, 호환성이 충족되면 됩니다.

Enterprise Edition에서 Community Edition으로 프로젝트를 내보내는 경우 Enterprise Edition에서만 유지되는 데이터가 손실될 수 있습니다. 자세한 내용은 EE에서 CE로 복원을 참조하세요.

프로젝트 및 데이터 내보내기#

프로젝트를 가져오기 전에 먼저 내보내야 합니다.

사전 요구사항:

• 내보내지는 항목 목록을 검토합니다. 모든 항목이 내보내지지는 않습니다.
• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.
• 많은 수의 Git 참조가 있는 저장소의 성능을 크게 향상시키려면 GitLab 18.0 이상을 사용합니다. 자세한 내용은 GitLab 저장소 백업 시간 단축에 관한 블로그 포스트를 참조하세요.

프로젝트 및 데이터를 내보내려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 설정 > 일반을 선택합니다.
3. 고급을 확장합니다.
4. 프로젝트 내보내기를 선택합니다.
5. 내보내기가 생성된 후 다음을 할 수 있습니다:
   • 받은 이메일에 포함된 링크를 따라갑니다.
   • 프로젝트 설정 페이지를 새로 고치고 프로젝트 내보내기 영역에서 내보내기 다운로드를 선택합니다.

내보내기는 구성된 shared_path, 임시 공유 디렉토리(기본적으로 <shared_path>/tmp/gitlab_exports)에서 생성된 다음 다음으로 이동됩니다:

• 구성된 uploads_directory.
• 객체 스토리지에 업로드.

24시간마다 워커가 이 내보내기 파일을 삭제합니다.

내보내지는 프로젝트 항목#

내보내지는 프로젝트 항목은 사용하는 GitLab 버전에 따라 다릅니다. 특정 프로젝트 항목이 내보내지는지 확인하려면:

1. exporters 배열을 확인합니다.
2. GitLab 버전의 프로젝트에 대한 project/import_export.yml 파일을 확인합니다.

빠른 개요를 위해 내보내지는 항목에는 다음이 포함됩니다:

• 프로젝트 및 위키 저장소
• 프로젝트 업로드
• 통합을 제외한 프로젝트 구성
• 이슈
  • 이슈 댓글
  • 이슈 반복(GitLab 15.4에서 도입)
  • 이슈 리소스 상태 이벤트(GitLab 15.4에서 도입)
  • 이슈 리소스 마일스톤 이벤트(GitLab 15.4에서 도입)
  • 이슈 리소스 반복 이벤트(GitLab 15.4에서 도입)
• 머지 리퀘스트
  • 머지 리퀘스트 diffs
  • 머지 리퀘스트 댓글
  • 머지 리퀘스트 리소스 상태 이벤트(GitLab 15.4에서 도입)
  • 머지 리퀘스트 다중 담당자(GitLab 15.3에서 도입)
  • 머지 리퀘스트 검토자(GitLab 15.3에서 도입)
  • 머지 리퀘스트 승인자(GitLab 15.3에서 도입)
• 커밋 댓글(GitLab 15.10에서 도입)
• 레이블
• 마일스톤
• 스니펫
• 릴리스
• 시간 추적 및 기타 프로젝트 엔터티
• 디자인 관리 파일 및 데이터
• LFS 객체
• 이슈 보드
• CI/CD 파이프라인(아카이브)
• 파이프라인 스케줄(비활성 및 가져오기를 시작한 사용자에게 할당)
• 보호된 브랜치 및 태그
• 푸시 규칙
• 이모지 반응
• 직접 프로젝트 멤버(내보낸 프로젝트 그룹에 대한 Maintainer 또는 Owner 권한이 있는 경우)
• 상속된 프로젝트 멤버를 직접 프로젝트 멤버로(내보낸 프로젝트 그룹에 대한 Owner 권한이나 인스턴스에 대한 관리자 접근 권한이 있는 경우)
• 일부 머지 리퀘스트 승인 규칙:
  • 보호된 브랜치에 대한 승인
  • 자격을 갖춘 승인자
• 취약점 보고서(GitLab 17.7에서 도입)

내보내지지 않는 프로젝트 항목#

내보내지지 않는 항목에는 다음이 포함됩니다:

• 자식 파이프라인 히스토리
• 파이프라인 트리거
• CI/CD job 추적 및 아티팩트
• 패키지 및 컨테이너 레지스트리 이미지
• CI/CD 변수
• CI/CD job 토큰 허용 목록
• 웹훅
• 암호화된 토큰
• 필수 승인 수
• 저장소 크기 제한
• 보호된 브랜치에 푸시를 허용하는 배포 키
• 보안 파일
• Git 관련 이벤트에 대한 활동 로그(예: 푸시 및 태그 생성)
• 프로젝트와 관련된 보안 정책
• 이슈와 연결된 항목 간의 링크
• 관련 머지 리퀘스트 링크
• 파이프라인 스케줄 변수

프로젝트 및 데이터 가져오기#

프로젝트와 데이터를 가져올 수 있습니다. 가져올 수 있는 데이터 양은 최대 가져오기 파일 크기에 따라 다릅니다:

• GitLab Self-Managed에서 관리자는 최대 가져오기 파일 크기를 설정할 수 있습니다.
• GitLab.com에서는 값이 5GB로 설정됩니다.

사전 요구사항#

히스토리

• Developer 권한 대신 Maintainer 권한 요구사항이 GitLab 16.0에 도입되었고 GitLab 15.11.1 및 GitLab 15.10.5에 백포트되었습니다.

• 프로젝트 및 데이터를 내보냈어야 합니다.
• GitLab 버전을 비교하고 내보낸 GitLab 버전과 같거나 더 높은 GitLab 버전으로 가져오고 있는지 확인합니다.
• 문제가 있는지 호환성을 검토합니다.
• 마이그레이션할 대상 그룹에 대한 Maintainer 또는 Owner 권한.
• 소스 및 대상 GitLab 인스턴스 모두에 tar 명령이 설치되어 있어야 합니다.

프로젝트 가져오기#

프로젝트를 가져오려면:

1. 오른쪽 상단 모서리에서 새로 만들기(+) 및 새 프로젝트/저장소를 선택합니다.
2. 프로젝트 가져오기를 선택합니다.
3. 다음에서 프로젝트 가져오기에서 GitLab 내보내기를 선택합니다.
4. 프로젝트 이름과 URL을 입력합니다. 그런 다음 이전에 내보낸 파일을 선택합니다.
5. 프로젝트 가져오기를 선택합니다.

API를 사용하여 가져오기 상태를 쿼리할 수 있습니다. 쿼리가 가져오기 오류나 예외를 반환할 수 있습니다.

가져온 항목의 변경사항#

내보낸 항목은 다음과 같이 변경되어 가져옵니다:

• Owner 권한을 가진 프로젝트 멤버는 Maintainer 권한으로 가져옵니다.
• 가져온 프로젝트에 포크에서 발생한 머지 리퀘스트가 포함된 경우 이러한 머지 리퀘스트와 관련된 새 브랜치가 프로젝트에 생성됩니다. 따라서 새 프로젝트의 브랜치 수가 소스 프로젝트보다 많을 수 있습니다.
• 내부 공개 수준이 제한된 경우 가져온 모든 프로젝트에 비공개 공개 수준이 부여됩니다.

배포 키는 가져오지 않습니다. 배포 키를 사용하려면 가져온 프로젝트에서 활성화하고 보호된 브랜치를 업데이트해야 합니다.

대용량 프로젝트 가져오기#

더 큰 프로젝트가 있는 경우 Rake 태스크 사용을 고려하세요.

최대 가져오기 파일 크기 설정#

관리자는 다음 두 가지 방법 중 하나로 최대 가져오기 파일 크기를 설정할 수 있습니다:

• Application settings API의 max_import_size 옵션 사용.
• Admin 영역 UI에서.

기본값은 0(무제한)입니다.

속도 제한#

남용을 방지하기 위해 기본적으로 사용자는 속도 제한이 있습니다:

내보내기 파일을 업로드하여 그룹 마이그레이션(더 이상 사용되지 않음)#

히스토리

• GitLab 14.6에서 더 이상 사용되지 않음.

사전 요구사항:

• 마이그레이션할 그룹에 대한 Owner 권한.

파일 내보내기를 사용하면 다음을 할 수 있습니다:

• 모든 그룹을 파일로 내보내고 해당 파일을 다른 GitLab 인스턴스 또는 동일한 인스턴스의 다른 위치에 업로드합니다.
• GitLab UI 또는 API를 사용합니다.
• 그룹을 하나씩 마이그레이션하고 그룹의 각 프로젝트를 하나씩 내보내고 가져옵니다.

관리자 접근 토큰을 사용하여 가져오기를 수행하면 GitLab이 사용자 기여를 올바르게 매핑합니다. GitLab Self-Managed 인스턴스에서 GitLab.com으로 가져올 때는 사용자 기여를 올바르게 매핑하지 않습니다.

관련 주제#

• 프로젝트 가져오기 및 내보내기 API
• 프로젝트 가져오기 및 내보내기 관리 Rake 태스크
• GitLab 그룹 마이그레이션
• 그룹 가져오기 및 내보내기 API
• 직접 전송으로 그룹 마이그레이션