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

이 API를 사용한 후 프로젝트의 CI/CD 변수를 보존하려면 프로젝트 수준 CI/CD 변수 API를 사용할 수 있습니다.

일련의 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에 업로드하는 경우 upload[url]을 생성하려면 객체 업로드를 위한 사전 서명된 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 16.0에서 Developer 역할 대신 Maintainer 역할 요구 사항이 도입되었습니다.
• 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이어야 합니다.

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

히스토리

• 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: 가져오기를 완료할 수 없었습니다.

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

히스토리

• GitLab 15.11에서 일반 사용 가능. 기능 플래그 import_project_from_remote_file_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
    }
  }
}