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

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

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

프로젝트 가져오기 및 내보내기 API를 사용하기 전에, 아마도 group import and export API 를 사용하고 싶어할 것입니다.

프로젝트 가져오기 및 내보내기 API를 사용한 후에, 아마도 프로젝트 수준 CI/CD 변수 API 를 사용하고 싶어할 것입니다.

Docker pulls and pushes를 통해 Container Registry를 아직 이전해야 합니다. 모든 빌드 아티팩트를 검색하기 위해 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 integer 또는 string yes 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path
upload[url] string yes 프로젝트를 업로드할 URL
description string no 프로젝트 설명을 재정의합니다.
upload 해시 no 내보낸 프로젝트를 웹 서버로 업로드하는 정보를 포함하는 해시
upload[http_method] string no 내보낸 프로젝트를 업로드하는 데 사용되는 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 integer 또는 string yes 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path 
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 integer 또는 string yes 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로 
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에 소개된 유지관리자 역할의 요구사항은 개발자 역할 대신 도입되었으며, GitLab 15.11.1 및 GitLab 15.10.5로 되연되었습니다. 
POST /projects/import
속성 유형 필수 설명
file string yes 업로드할 파일입니다.
path string yes 새 프로젝트의 이름과 경로입니다.
name string no 가져올 프로젝트의 이름입니다. 제공되지 않으면 프로젝트의 경로로 기본 설정됩니다.
namespace integer or string no 프로젝트를 가져올 네임스페이스의 ID 또는 경로입니다. 기본적으로 현재 사용자의 네임스페이스로 설정됩니다.

가져오기 대상 그룹에서 유지관리자 역할이 적어도 필요합니다.
override_params Hash no 프로젝트 API에서 정의된 모든 필드를 지원합니다.
overwrite boolean no 가져올 프로젝트와 동일한 경로에 프로젝트가 있는 경우 가져오기를 덮어쓰기합니다. 기본값은 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": "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": []
}
note
최대 가져오기 파일 크기는 관리자가 설정할 수 있습니다. 기본값은 0 (무제한)입니다. 관리자로서 최대 가져오기 파일 크기를 수정할 수 있습니다. 이를 위해 응용 프로그램 설정 API나 관리자 영역에서 max_import_size 옵션을 사용하십시오. 기본값은 GitLab 13.8에서 50MB에서 0으로 수정되었습니다.

원격 객체 리포지터리에서 파일 가져오기

상태: Beta
  • GitLab 13.12에서 Beta로 도입되었습니다. import_project_from_remote_file라는 플래그가 기본으로 활성화됩니다.
Self-managed GitLab에서는 기본적으로이 기능을 사용할 수 있습니다. 기능을 숨기려면 관리자가 import_project_from_remote_file이라는 플래그를 비활성화 할 수 있습니다. GitLab.com 및 전용 GitLab에서는이 기능을 사용할 수 있습니다.
POST /projects/remote-import
속성 유형 필수 설명
path string yes 새 프로젝트의 이름과 경로입니다.
url string yes 가져올 파일의 URL입니다.
name string no 가져올 프로젝트의 이름입니다. 제공되지 않으면 프로젝트의 경로로 기본 설정됩니다.
namespace integer or string no 프로젝트를 가져올 네임스페이스의 ID 또는 경로입니다. 기본적으로 현재 사용자의 네임스페이스로 설정됩니다.
overwrite boolean no 가져올 때 동일한 경로에 프로젝트를 덮어쓸지 여부입니다. 기본값은 false입니다.
override_params Hash no 프로젝트 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": "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 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": "관리자 / 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 배열에는 다음과 같은 이유로 가져오기에 실패한 관계의 어떤 발생을 모두 포함할 수 있습니다:

  • 복구할 수 없는 오류.
  • 재시도가 고갈됨. 전형적인 예: 쿼리 시간 초과.
note
failed_relations 배열의 각 요소의 id 필드는 관계가 아니라 실패 레코드를 참조합니다.
note
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
    }
  }
}

관련 주제