프로젝트 가져오기 및 내보내기 API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

파일 전송을 사용하여 프로젝트 가져오기 및 내보내기 API를 사용하여 프로젝트를 가져오고 내보냅니다.

프로젝트 가져오기 및 내보내기 API를 사용하기 전에 다음을 사용해보길 권장합니다. 그룹 가져오기 및 내보내기 API.

프로젝트 가져오기 및 내보내기 API를 사용한 후에는 다음을 사용해보길 원할 수 있습니다. 프로젝트 수준 CI/CD 변수 API.

당신은 여전히 시리즈의 Docker pull 및 push를 통해 컨테이너 레지스트리 를 마이그레이션해야 합니다. 어떠한 CI/CD 파이프라인도 재실행하여 빌드 결과물을 검색하세요.

전제 조건

프로젝트 가져오기 및 내보내기 API의 전제 조건은 다음을 참조하십시오.

내보내기 일정화

새로운 내보내기를 시작하세요.

이 엔드포인트는 upload 해시 매개변수도 허용합니다. 이는 내보낸 프로젝트를 웹 서버나 S3 호환 플랫폼에 업로드하는 데 필요한 모든 정보를 포함합니다. 내보내기에 대해, GitLab은:

  • 최종 서버로의 이진 데이터 파일 업로드만을 지원합니다.
  • 업로드 요청에 Content-Type: application/gzip 헤더를 보냅니다. 사전 서명된 URL이 이러한 내용을 시그네처의 일부로 포함하도록 보장하세요.
  • 프로젝트 내보내기 프로세스를 완료하는 데 시간이 걸릴 수 있습니다. 업로드 URL이 내보내기 프로세스 동안 짧은 만료 시간을 가지지 않도록하고 내보내기 프로세스 중에 항상 사용 가능한지 확인하세요.
  • 관리자는 최대 내보내기 파일 크기를 수정할 수 있습니다. 기본적으로 최대 크기는 무제한(0)입니다. 이를 변경하려면 max_export_size를 다음 중 하나를 사용하여 편집하세요.
  • GitLab.com에서 최대 가져오기 파일 크기에 대한 고정된 한도가 있습니다. 자세한 내용은 계정 및 한도 설정을 참조하세요.

upload[url] 매개변수는 upload 매개변수가 있는 경우 필요합니다.

Amazon S3로 업로드하는 경우 객체 업로드를 위한 사전 서명된 URL 생성 문서 스크립트를 참조하여 upload[url]을 생성하세요. 

POST /projects/:id/export
속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩 된 경로.
upload[url] 문자열 예 프로젝트를 업로드할 URL.
description 문자열 아니요 프로젝트 설명을 재정의합니다.
upload 해시 아니요 내보낸 프로젝트를 웹 서버로 업로드하는 데 필요한 정보를 포함하는 해시입니다.
upload[http_method] 문자열 아니요 내보낸 프로젝트를 업로드하는 데 사용되는 HTTP 메서드입니다. PUT 및 POST 메서드만 허용됩니다. 기본값은 PUT입니다. 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
    "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=AKIAIMBJHN2O62W8IELQ%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
속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩 된 경로. 
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "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

| 속성 | 유형 | 필수 | 설명 | | —- | —| — | —- | | id | 정수 또는 문자열 | 예 | 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path | shell curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ --remote-name "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에 소개된 Maintainer 역할 요구 사항은 개발자 역할 대신에 사용되며, GitLab 15.11.1 및 GitLab 15.10.5로 되돌아갑니다. 
POST /projects/import
속성 유형 필수 설명
file 문자열 예 업로드할 파일.
path 문자열 예 새 프로젝트의 이름과 경로.
name 문자열 아니요 가져올 프로젝트의 이름. 제공되지 않으면 프로젝트의 경로가 기본값으로 사용됩니다.
namespace 정수 또는 문자열 아니요 프로젝트를 가져올 네임스페이스의 ID 또는 경로. 기본값은 현재 사용자의 네임스페이스입니다.

가져오고자 하는 그룹의 유지자(Maintainer) 역할이 최소한 필요합니다.
override_params 해시 아니요 프로젝트 API에서 정의된 모든 필드를 지원합니다.
overwrite 부울 아니요 동일한 경로에 프로젝트가 있는 경우 가져올 때 덮어쓰기할지 여부. 기본값은 false입니다.

전달된 기능적으로 우선시 되는 재정의 매개변수는 내보내기 파일 내에서 정의된 모든 값보다 우선합니다.

파일 시스템에서 파일을 업로드하려면 --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" "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": "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": "관리자 / 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": []
}

참고: 최대 가져오기 파일 크기는 관리자에 의해 설정될 수 있습니다. 기본값은 0 (무제한)입니다. 관리자로서 최대 가져오기 파일 크기를 수정할 수 있습니다. Application settings API 또는 관리자 영역에서 max_import_size 옵션을 사용하십시오. GitLab 13.8에서 기본값 수정됨: 50MB에서 0으로 변경됨.

원격 객체 저장소에서 파일 가져오기

상태: 베타
자체 관리되는 GitLab의 경우, 기본적으로이 기능을 사용할 수 있습니다. 기능을 숨기려면 관리자가 import_project_from_remote_file라는 기능 플래그를 비활성화 할 수 있습니다. GitLab.com 및 전용 GitLab의 경우,이 기능을 사용할 수 있습니다.
POST /projects/remote-import
속성 유형 필수 설명
path 문자열 예 새 프로젝트의 이름과 경로.
url 문자열 예 가져올 파일의 URL.
name 문자열 아니요 가져오려는 프로젝트의 이름. 제공되지 않으면 프로젝트의 경로가 기본값으로 사용됩니다.
namespace 정수 또는 문자열 아니요 프로젝트를 가져올 네임스페이스의 ID 또는 경로. 기본값은 현재 사용자의 네임스페이스입니다.
overwrite 부울 아니요 가져올 때 동일한 경로에 프로젝트를 덮어쓸지 여부. 기본값은 false입니다.
override_params 해시 아니요 프로젝트 API에서 정의된 모든 필드를 지원합니다.

전달된 재정의 매개변수는 내보낸 파일의 정의된 값보다 우선합니다. 

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": "관리자 / 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 14.9에서 베타로 도입됨. 기본 설정에서 비활성화된 상태로 import_project_from_remote_file_s3라는 플래그로 제공됩니다.
  • GitLab 14.10에서 GitLab.com에서 활성화됨.
  • GitLab 15.11에서 self-managed에서 활성화됨. 기능 플래그 import_project_from_remote_file_s3가 제거되었습니다. 
POST /projects/remote-import-s3
속성 유형 필수 설명
access_key_id 문자열 예 AWS S3 액세스 키 ID.
bucket_name 문자열 예 파일이 저장된 AWS S3 버킷 이름.
file_key 문자열 예 파일을 식별하기 위한 AWS S3 파일 키.
path 문자열 예 새 프로젝트의 전체 경로.
region 문자열 예 파일이 저장된 AWS S3 지역 이름.
secret_access_key 문자열 예 AWS S3 비밀 액세스 키.
name 문자열 아니요 가져올 프로젝트의 이름. 제공되지 않으면 기본값은 프로젝트의 경로입니다.
namespace 정수 또는 문자열 아니요 프로젝트를 가져올 네임스페이스의 ID 또는 경로. 기본값은 현재 사용자의 네임스페이스입니다.

전달된 재정의 매개변수는 내보내기 파일에 정의된 모든 값보다 우선합니다. 

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": "샘플 프로젝트",
  "path": "sample-project",
  "region": "<Your S3 region name>",
  "bucket_name": "<Your S3 bucket name>",
  "file_key": "<Your S3 file key>",
  "access_key_id": "<Your AWS access key id>",
  "secret_access_key": "<Your AWS 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": "example-group"
}
headers = {
    'Private-Token': "<your_access_token>"
}

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

{
  "id": 1,
  "description": null,
  "name": "샘플 프로젝트",
  "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
속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로. 
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/1/import"

상태는 다음 중 하나일 수 있습니다:

  • none
  • scheduled
  • failed
  • started
  • finished

상태가 failed인 경우 import_error 아래에 가져오기 오류 메시지가 포함됩니다. 상태가 failed, started, 또는 finished인 경우 failed_relations 배열에 아래 중 하나로 인해 가져오기에 실패한 관계가 포함될 수 있습니다:

  • 복구할 수 없는 오류.
  • 재시도가 고갈된 경우. 전형적인 예시: 쿼리 시간 초과.

참고: failed_relations 배열의 요소 id 필드는 관계가 아닌 실패 레코드를 참조합니다.

참고: failed_relations 배열의 항목 수는 100개로 제한됩니다. 

{
  "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
    }
  }
}

관련 주제