이 API로 프로젝트를 마이그레이션합니다. 그룹 가져오기·내보내기 API로 상위 그룹 구조를 먼저 마이그레이션하면 프로젝트 이슈와 그룹 에픽의 연결처럼 그룹 수준의 관계를 보존할 수 있습니다.

이 API를 사용한 다음에는 프로젝트 수준 CI/CD 변수 API로 프로젝트의 CI/CD 변수를 보존할 수 있습니다.

컨테이너 레지스트리는 Docker pull과 push를 반복해 직접 마이그레이션해야 합니다. 빌드 아티팩트를 다시 확보하려면 CI/CD 파이프라인을 다시 실행합니다.

사전 준비 사항:

• 프로젝트 내보내기는 프로젝트와 데이터 내보내기를 참고합니다.
• 프로젝트 가져오기는 프로젝트와 데이터 가져오기를 참고합니다.

프로젝트 내보내기#

지정한 프로젝트를 내보냅니다.

upload 해시 파라미터로 내보낸 프로젝트를 웹 서버나 S3 호환 플랫폼에 업로드합니다. 내보내기에서 GitLab은 다음과 같이 동작합니다.

• 최종 서버로는 바이너리 데이터 파일 업로드만 지원합니다.
• 업로드 요청에 Content-Type: application/gzip 헤더를 함께 보냅니다. 사전 서명된 URL의 서명에 이 헤더가 포함되도록 합니다.
• 프로젝트 내보내기 과정이 완료되기까지 시간이 걸릴 수 있습니다. 업로드 URL의 만료 시간을 너무 짧게 두지 말고 내보내기 과정 내내 사용할 수 있도록 합니다.
• 관리자는 최대 내보내기 파일 크기를 변경할 수 있습니다. 기본값은 무제한(0)입니다. 변경하려면 다음 중 한 가지 방법으로 max_export_size를 수정합니다.
  • GitLab UI.
  • 애플리케이션 설정 API
• GitLab.com에서는 최대 가져오기 파일 크기가 고정되어 있습니다. 자세한 내용은 계정 및 한도 설정을 참고합니다.

upload 파라미터를 사용하면 upload[url] 파라미터가 필수입니다.

Amazon S3로 업로드할 때는 객체 업로드용 사전 서명 URL 생성 문서의 스크립트를 참고해 upload[url]을 생성합니다. 알려진 이슈 때문에 Amazon S3에는 최대 5GB 크기의 파일만 업로드할 수 있습니다.

POST /projects/:id/export

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/export" \
  --data "upload[http_method]=PUT" \
  --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<your_access_token>%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd"

{
  "message": "202 Accepted"
}

프로젝트 내보내기 상태 조회#

지정한 프로젝트의 가장 최근 내보내기 상태를 조회합니다.

GET /projects/:id/export

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/export"

상태는 다음 중 하나입니다.

• none: 대기 중이거나 시작·완료된 내보내기가 없고 재생성 중인 내보내기도 없습니다.
• queued: 내보내기 요청이 접수되어 처리 대기열에 있습니다.
• started: 내보내기 과정이 시작되어 진행 중입니다. 여기에는 다음이 포함됩니다.
  • 내보내기 처리.
  • 결과 파일에 대한 작업. 예를 들어 파일을 내려받으라는 알림 메일을 사용자에게 보내거나, 내보낸 파일을 웹 서버에 업로드하는 작업입니다.
• finished: 내보내기 과정이 끝나고 사용자에게 알림이 전달된 상태입니다.
• regeneration_in_progress: 내려받을 수 있는 내보내기 파일이 있고, 새 내보내기 생성 요청이 처리 중입니다.

_links는 내보내기가 완료된 경우에만 포함됩니다.

created_at은 프로젝트 생성 시각이며 내보내기 시작 시각이 아닙니다.

{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "export_status": "finished",
  "_links": {
    "api_url": "https://gitlab.example.com/api/v4/projects/1/export/download",
    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/download_export"
  }
}

프로젝트 내보내기 파일 다운로드#

지정한 프로젝트의 가장 최근 내보내기 파일을 내려받습니다.

GET /projects/:id/export/download

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --remote-header-name \
  --remote-name \
  --url "https://gitlab.example.com/api/v4/projects/5/export/download"

ls *export.tar.gz
2017-12-05_22-11-148_namespace_project_export.tar.gz

로컬 아카이브에서 프로젝트 가져오기#

히스토리

• GitLab 18.7에서 namespace_id와 namespace_path 속성이 추가되었습니다.

로컬 아카이브에서 프로젝트를 가져옵니다.

POST /projects/import

전달한 재정의 파라미터는 내보내기 파일에 정의된 모든 값보다 우선합니다.

파일 시스템의 파일을 업로드하려면 --form 인수를 사용합니다. 이렇게 하면 cURL 이 Content-Type: multipart/form-data 헤더로 데이터를 전송합니다. file= 파라미터는 파일 시스템의 파일을 가리켜야 하며 앞에 @를 붙여야 합니다. 예를 들면 다음과 같습니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "path=api-project" \
  --form "file=@/path/to/file" \
  --url "https://gitlab.example.com/api/v4/projects/import"

cURL은 원격 서버의 파일 전송을 지원하지 않습니다. 다음은 Python의 open 메서드로 프로젝트를 가져오는 예시입니다.

import requests

url =  'https://gitlab.example.com/api/v4/projects/import'
files = { "file": open("project_export.tar.gz", "rb") }
data = {
    "path": "example-project",
    "namespace_path": "example-group"
}
headers = {
    'Private-Token': "<your_access_token>"
}

requests.post(url, headers=headers, data=data, files=files)

{
  "id": 1,
  "description": null,
  "name": "api-project",
  "name_with_namespace": "Administrator / api-project",
  "path": "api-project",
  "path_with_namespace": "root/api-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": []
}

원격 아카이브에서 프로젝트 가져오기#

히스토리

• GitLab 18.7에서 namespace_id와 namespace_path 속성이 추가되었습니다.

원격 아카이브에서 프로젝트를 가져옵니다.

POST /projects/remote-import

전달한 재정의 파라미터는 내보내기 파일에 정의된 모든 값보다 우선합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/remote-import" \
  --data '{"url":"https://remoteobject/file?token=123123","path":"remote-project"}'

{
  "id": 1,
  "description": null,
  "name": "remote-project",
  "name_with_namespace": "Administrator / remote-project",
  "path": "remote-project",
  "path_with_namespace": "root/remote-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [],
  "import_error": null
}

Content-Length 헤더는 유효한 숫자를 반환해야 합니다. 최대 파일 크기는 10GB 입니다. Content-Type 헤더는 application/gzip 이어야 합니다.

AWS S3 버킷에서 프로젝트 가져오기#

히스토리

• GitLab 18.7에서 namespace_id와 namespace_path 속성이 추가되었습니다.

지정한 AWS S3 버킷에 저장된 아카이브에서 프로젝트를 가져옵니다.

POST /projects/remote-import-s3

전달한 재정의 파라미터는 내보내기 파일에 정의된 모든 값보다 우선합니다.

curl --request POST \
  --url "https://gitlab.example.com/api/v4/projects/remote-import-s3" \
  --header "PRIVATE-TOKEN: <your gitlab access key>" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Sample Project",
  "path": "sample-project",
  "region": "",
  "bucket_name": "",
  "file_key": "",
  "access_key_id": "",
  "secret_access_key": ""
}'

다음은 Amazon S3에 접속하는 모듈을 사용해 Amazon S3 버킷에서 가져오는 예시입니다.

import requests
from io import BytesIO

s3_file = requests.get(presigned_url)

url =  'https://gitlab.example.com/api/v4/projects/import'
files = {'file': ('file.tar.gz', BytesIO(s3_file.content))}
data = {
    "path": "example-project",
    "namespace_path": "example-group"
}
headers = {
    'Private-Token': "<your_access_token>"
}

requests.post(url, headers=headers, data=data, files=files)

{
  "id": 1,
  "description": null,
  "name": "Sample project",
  "name_with_namespace": "Administrator / sample-project",
  "path": "sample-project",
  "path_with_namespace": "root/sample-project",
  "created_at": "2018-02-13T09:05:58.023Z",
  "import_status": "scheduled",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [],
  "import_error": null
}

프로젝트 가져오기 상태 조회#

지정한 프로젝트의 가장 최근 가져오기 상태를 조회합니다.

GET /projects/:id/import

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/import"

상태는 다음 중 하나입니다.

• none
• scheduled
• failed
• started
• finished

상태가 failed 이면 import_error에 가져오기 오류 메시지가 포함됩니다. 상태가 failed, started, finished 이면 다음과 같은 이유로 가져오지 못한 관계가 failed_relations 배열에 담길 수 있습니다.

• 복구할 수 없는 오류.
• 재시도 횟수 소진. 대표적인 예는 쿼리 타임아웃입니다.

{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "import_status": "started",
  "import_type": "github",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [
    {
      "id": 42,
      "created_at": "2020-04-02T14:48:59.526Z",
      "exception_class": "RuntimeError",
      "exception_message": "A failure occurred",
      "source": "custom error context",
      "relation_name": "merge_requests",
      "line_number": 0
    }
  ]
}

GitHub에서 가져올 때는 stats 필드에 GitHub에서 이미 가져온 객체 수와 이미 반영된 객체 수가 표시됩니다.

{
  "id": 1,
  "description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
  "name": "Gitlab Test",
  "name_with_namespace": "Gitlab Org / Gitlab Test",
  "path": "gitlab-test",
  "path_with_namespace": "gitlab-org/gitlab-test",
  "created_at": "2017-08-29T04:36:44.383Z",
  "import_status": "started",
  "import_type": "github",
  "correlation_id": "mezklWso3Za",
  "failed_relations": [
    {
      "id": 42,
      "created_at": "2020-04-02T14:48:59.526Z",
      "exception_class": "RuntimeError",
      "exception_message": "A failure occurred",
      "source": "custom error context",
      "relation_name": "merge_requests",
      "line_number": 0
    }
  ],
  "stats": {
    "fetched": {
      "diff_note": 19,
      "issue": 3,
      "label": 1,
      "note": 3,
      "pull_request": 2,
      "pull_request_merged_by": 1,
      "pull_request_review": 16
    },
    "imported": {
      "diff_note": 19,
      "issue": 3,
      "label": 1,
      "note": 3,
      "pull_request": 2,
      "pull_request_merged_by": 1,
      "pull_request_review": 16
    }
  }
}

프로젝트 리소스 가져오기#

히스토리

• GitLab 16.11에서 single_relation_import 기능 플래그와 함께 베타로 도입되었습니다. 기본으로 비활성입니다.
• GitLab 17.1에서 일반 공급으로 전환되었습니다. single_relation_import 기능 플래그는 제거되었습니다.

프로젝트 아카이브에 포함된 프로젝트 리소스를 가져옵니다. 가져올 항목의 유형은 relation 속성으로 지정합니다. 이미 가져온 항목은 건너뜁니다.

필요한 프로젝트 내보내기 파일은 로컬 아카이브에서 프로젝트 가져오기에 설명된 구조와 크기 요건을 그대로 따릅니다.

• 압축을 푼 파일은 GitLab 프로젝트 내보내기 구조를 따라야 합니다.
• 아카이브는 관리자가 설정한 최대 가져오기 파일 크기를 넘지 않아야 합니다.

POST /projects/import-relation

파일 시스템의 파일을 업로드하려면 --form 옵션을 사용합니다. 이렇게 하면 cURL 이 Content-Type: multipart/form-data 헤더로 데이터를 전송합니다. file= 파라미터는 파일 시스템의 파일을 가리켜야 하며 앞에 @를 붙여야 합니다. 예를 들면 다음과 같습니다.

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "path=api-project" \
  --form "file=@/path/to/file" \
  --form "relation=issues" \
  --url "https://gitlab.example.com/api/v4/projects/import-relation"

{
  "id": 9,
  "project_path": "namespace1/project1",
  "relation": "issues",
  "status": "finished"
}

프로젝트 리소스 가져오기 상태 조회#

히스토리

• GitLab 16.11에서 도입되었습니다.

지정한 프로젝트의 가장 최근 관계 가져오기 상태를 조회합니다. 한 번에 하나의 관계 가져오기만 예약할 수 있으므로, 이 엔드포인트로 이전 가져오기가 정상적으로 완료되었는지 확인할 수 있습니다.

GET /projects/:id/relation-imports

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/18/relation-imports"

[
  {
    "id": 1,
    "project_path": "namespace1/project1",
    "relation": "issues",
    "status": "created",
    "created_at": "2024-03-25T11:03:48.074Z",
    "updated_at": "2024-03-25T11:03:48.074Z"
  }
]

상태는 다음 중 하나입니다.

• created: 가져오기가 예약되었지만 아직 시작되지 않았습니다.
• started: 가져오기가 처리 중입니다.
• finished: 가져오기가 완료되었습니다.
• failed: 가져오기를 완료하지 못했습니다.