히스토리

• 대상 인스턴스에서 충돌을 피하기 위해 마일스톤 제목의 이름을 변경하는 기능이 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이 사용자와 사용자의 기여를 올바르게 매핑하도록 하려면:

• 프로젝트에 액세스할 수 있는 모든 멤버(직접 멤버와 상속된 멤버)의 정보가 내보낸 파일에 포함되도록 프로젝트 최상위 그룹의 Owner가 프로젝트를 내보내야 합니다. 프로젝트의 Maintainer와 Owner도 프로젝트 내보내기를 시작할 수 있습니다. 다만 그 경우에는 프로젝트의 직접 멤버만 내보내집니다.
• 관리자가 가져오기를 수행해야 합니다.
• 필요한 사용자가 대상 GitLab 인스턴스에 있어야 합니다. 관리자는 Rails 콘솔에서 일괄로, 또는 UI에서 하나씩 확인된 사용자를 만들 수 있습니다.
• 사용자는 소스 GitLab 인스턴스에서 대상 GitLab 인스턴스의 기본 이메일 주소와 일치하는 공개 이메일을 프로필에 설정해야 합니다. 프로젝트 내보내기 파일 편집으로 사용자의 공개 이메일을 수동으로 추가할 수도 있습니다.
• GitLab 18.4 이상에서는 기존 그룹으로 프로젝트를 직접 가져오면서 직접 멤버십을 만들 때 Users cannot be added to projects in this group 설정이 적용됩니다.

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

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

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

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

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

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

프로젝트 내보내기 파일을 편집하려면 다음과 같이 진행합니다:

1. 내보낸 .tar.gz 파일을 추출합니다.
2. 해당하는 파일을 편집합니다. 예를 들어 tree/project/project_members.ndjson 입니다.
3. 파일을 다시 .tar.gz 파일로 압축합니다.

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

호환성#

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

가져올 수 있는 프로젝트 파일 내보내기는 최대 두 개의 마이너 버전 이전 GitLab에서 내보낸 것까지입니다.

예를 들어:

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

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

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

대상 인스턴스의 가져오기 소스로 파일 내보내기를 활성화하려면 다음과 같이 진행합니다:

1. 오른쪽 위 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Import and export settings를 확장합니다.
4. Import sources로 스크롤합니다.
5. GitLab export 체크박스를 선택합니다.

CE와 EE 간#

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

Enterprise Edition에서 Community Edition으로 프로젝트를 내보내는 경우, Enterprise Edition에서만 유지되는 데이터가 손실될 수 있습니다. 자세한 내용은 EE에서 CE로 되돌리기를 참고합니다.

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

프로젝트를 가져오려면 먼저 내보내야 합니다.

사전 요구 사항:

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

프로젝트와 데이터를 내보내려면 다음 단계를 따릅니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Advanced를 확장합니다.
4. Export project를 선택합니다.
5. 내보내기가 생성된 후에는 다음을 할 수 있습니다:
   • 받은 이메일에 포함된 링크를 따라갑니다.
   • 프로젝트 설정 페이지를 새로 고치고 Export project 영역에서 Download export를 선택합니다.

내보내기는 구성한 shared_path, 즉 임시 공유 디렉터리 (기본값은 <shared_path>/tmp/gitlab_exports)에서 생성되고, 그 다음 아래 중 하나가 수행됩니다:

• 구성한 uploads_directory로 이동됩니다.
• 오브젝트 스토리지에 업로드됩니다.

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

Sidekiq, Gitaly, GitLab 애플리케이션(Rails) 노드가 분리된 GitLab 인스턴스에서는 다음 shared_path 설정에 지정된 디렉터리를 모든 노드에서 사용할 수 있어야 합니다.

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

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

1. exporters 배열을 확인합니다.
2. 사용하는 GitLab 버전의 프로젝트용 project/import_export.yml 파일을 확인합니다. 예를 들어 GitLab 19.2의 경우 https://gitlab.com/gitlab-org/gitlab/-/blob/19-2-stable-ee/lib/gitlab/import_export/project/import_export.yml 입니다.

간단히 정리하면 내보내지는 항목에는 다음이 포함됩니다:

• 프로젝트 및 위키 리포지터리

• 프로젝트 업로드

• 통합을 제외한 프로젝트 구성

• 이슈

  • 이슈 댓글
  • 이슈 이터레이션
  • 이슈 리소스 상태 이벤트
  • 이슈 리소스 마일스톤 이벤트
  • 이슈 리소스 이터레이션 이벤트

• 머지 리퀘스트

  • 머지 리퀘스트 diff
  • 머지 리퀘스트 댓글
  • 머지 리퀘스트 리소스 상태 이벤트
  • 머지 리퀘스트 다중 담당자
  • 머지 리퀘스트 리뷰어
  • 머지 리퀘스트 승인자

• 커밋 댓글

• 레이블

• 마일스톤

• 스니펫

• 릴리스

• 시간 추적 및 기타 프로젝트 엔터티

• 디자인 관리 파일 및 데이터

• LFS 객체

• 이슈 보드

• CI/CD 파이프라인(아카이브됨)

• 파이프라인 스케줄(비활성 상태이며 가져오기를 시작한 사용자에게 할당됨)

• 보호된 브랜치 및 태그

• 푸시 규칙

• 이모지 반응

  [!note] 사용자 지정 이모지를 사용하는 이모지 반응은 같은 이름의 사용자 지정 이모지가 대상에 있는 경우에만 가져옵니다. 대상에 없는 사용자 지정 이모지를 참조하는 반응은 건너뜁니다.

• 직접 프로젝트 멤버 (내보낸 프로젝트의 그룹에 대한 Maintainer 또는 Owner 권한이 있는 경우)

• 상속된 프로젝트 멤버를 직접 프로젝트 멤버로 (내보낸 프로젝트의 그룹에 대한 Owner 권한이나 인스턴스에 대한 관리자 액세스 권한이 있는 경우)

• 일부 머지 리퀘스트 승인 규칙:

  • 보호된 브랜치에 대한 승인
  • 자격을 갖춘 승인자

• 취약점 보고서(GitLab 17.7에서 도입)

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

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

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

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

히스토리

• GitLab 19.5에서 원본 프로젝트의 생성 날짜를 유지하도록 변경되었습니다.

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

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

사전 요구 사항#

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

프로젝트 가져오기#

프로젝트를 가져오려면 다음과 같이 진행합니다:

1. 오른쪽 위 모서리에서 Create new (+)와 New project/repository를 선택합니다.
2. Import project를 선택합니다.
3. Import project from에서 GitLab export를 선택합니다.
4. 프로젝트 이름과 URL을 입력합니다. 그런 다음 앞서 내보낸 파일을 선택합니다.
5. Import project를 선택합니다.

API를 사용하여 가져오기 상태를 조회할 수 있습니다. 조회 결과로 가져오기 오류나 예외가 반환될 수 있습니다.

가져온 항목의 변경 사항#

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

• Owner 권한을 가진 프로젝트 멤버는 Maintainer 권한으로 가져와집니다.
• 가져온 프로젝트에 포크에서 시작된 머지 리퀘스트가 포함되어 있으면, 이러한 머지 리퀘스트와 연결된 새 브랜치가 프로젝트에 생성됩니다. 따라서 새 프로젝트의 브랜치 수가 소스 프로젝트의 브랜치 수보다 많을 수 있습니다.
• Internal 가시성 수준이 제한된 경우, 가져온 모든 프로젝트에는 Private 가시성이 부여됩니다.
• 보호된 브랜치와 보호된 태그의 액세스 수준은 Maintainers로 재설정됩니다. 예를 들어 Allowed to merge가 Developers + Maintainers로 설정되어 있으면 Maintainers가 됩니다. No one으로 설정된 액세스 수준은 유지됩니다.
  • 원래 액세스 수준을 유지하려면 가져오기를 수행하는 사용자가 대상 프로젝트의 최상위 그룹에 대한 Owner 권한을 갖고 있거나 GitLab 관리자여야 합니다.
  • 대상 프로젝트가 개인 네임스페이스에 있는 경우 액세스 수준은 항상 재설정됩니다.

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

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

프로젝트 규모가 큰 경우 Rake 태스크 사용을 고려합니다.

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

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

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

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

속도 제한#

남용을 방지하기 위해 기본적으로 사용자에게 다음과 같은 속도 제한이 적용됩니다:

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

히스토리

• GitLab 14.6에서 더 이상 사용되지 않습니다.
• GitLab 19.5에서 원본 그룹의 생성 날짜를 유지하도록 변경되었습니다.

사전 요구 사항:

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

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

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

관리자 액세스 토큰으로 가져오기를 수행하면 GitLab이 사용자 기여를 올바르게 매핑합니다. GitLab Self-Managed 인스턴스에서 GitLab.com으로 가져올 때는 GitLab이 사용자 기여를 올바르게 매핑하지 않습니다. GitLab Self-Managed 인스턴스에서 GitLab.com으로 가져올 때 사용자 기여의 올바른 매핑은 Professional Services 팀의 유상 참여로 보존할 수 있습니다.

추가 정보#

• 내보내기는 임시 디렉터리에 저장되며 전용 워커가 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 영역.
• GitLab.com에서는 크기가 5GB 이하인 가져오기 파일로만 그룹을 가져올 수 있습니다.

호환성#

그룹 파일 내보내기는 NDJSON 형식입니다.

가져올 수 있는 그룹 파일 내보내기는 최대 두 개의 마이너 버전 이전 GitLab에서 내보낸 것까지입니다.

예를 들어:

내보내지는 그룹 항목#

그룹용 import_export.yml 파일에는 파일 내보내기로 그룹을 마이그레이션할 때 내보내고 가져오는 항목이 나열되어 있습니다. 대상 GitLab 인스턴스로 가져올 수 있는 항목을 확인하려면 사용하는 GitLab 버전의 브랜치에서 이 파일을 봅니다. 예를 들어 19-2-stable-ee 브랜치의 import_export.yml 입니다.

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

• 마일스톤
• 그룹 레이블(연결된 레이블 우선순위는 제외)
• 보드 및 보드 목록
• 배지
• 하위 그룹(앞서 언급한 모든 데이터 포함)
• 에픽
  • 에픽 리소스 상태 이벤트.
• 이벤트
• 위키
• 이터레이션 케이던스.

내보내지지 않는 그룹 항목#

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

• 프로젝트
• 러너 토큰
• SAML 디스커버리 토큰
• 업로드

준비#

• 가져온 그룹에서 멤버 목록과 각 멤버의 권한을 보존하려면 이 그룹의 사용자를 검토합니다. 원하는 그룹을 가져오기 전에 이 사용자들이 존재하는지 확인합니다.
• 사용자는 소스 GitLab 인스턴스에서 대상 GitLab 인스턴스의 확인된 기본 이메일과 일치하는 공개 이메일을 설정해야 합니다. 대부분의 사용자는 이메일 주소를 확인하도록 요청하는 이메일을 받습니다.

그룹 내보내기#

사전 요구 사항:

• 그룹에 대한 Owner 권한이 있어야 합니다.

그룹의 콘텐츠를 내보내려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Advanced 섹션에서 Export group을 선택합니다.
4. 내보내기가 생성된 후에는 다음을 할 수 있습니다:
   • 받은 이메일에 포함된 링크를 따라갑니다.
   • 그룹 설정 페이지를 새로 고치고 Export project 영역에서 Download export를 선택합니다.

그룹 가져오기#

그룹을 가져오려면 다음과 같이 진행합니다:

1. 오른쪽 위 모서리에서 Create new (+)와 New group을 선택합니다.
2. Import group을 선택합니다.
3. Import group from file 섹션에서 그룹 이름을 입력하고 연결된 그룹 URL을 그대로 두거나 수정합니다.
4. Choose file을 선택합니다.
5. 가져올 GitLab 내보내기 파일을 선택합니다.
6. 가져오기를 시작하려면 Import를 선택합니다.

속도 제한#

남용을 방지하기 위해 기본적으로 사용자에게 다음과 같은 속도 제한이 적용됩니다:

관련 주제#

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