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

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

파일 전송을 사용하여 프로젝트를 가져오고 내보내기 위해 프로젝트 가져오기 및 내보내기 API를 사용하세요.

프로젝트 가져오기 및 내보내기 API를 사용하기 전에 그룹 가져오기 및 내보내기 API를 사용하는 것이 좋습니다.

프로젝트 가져오기 및 내보내기 API를 사용한 후에는 프로젝트 수준 CI/CD 변수 API를 사용하는 것이 좋습니다.

여전히 컨테이너 레지스트리를 Docker pulls 및 pushes의 시리즈를 통해 마이그레이션해야 합니다. 빌드 아티팩트를 검색하기 위해 모든 CI/CD 파이프라인을 다시 실행하세요.

전제 조건

프로젝트 가져오기 및 내보내기 API의 전제 조건은 다음을 참조하세요:

프로젝트 내보내기에 대한 전제 조건.
프로젝트 가져오기에 대한 전제 조건.

내보내기 예약

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

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

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

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

Amazon S3에 업로드하는 경우 객체 업로드를 위한 미리 서명된 URL 생성 문서를 참조하여 upload[url]을 생성하세요.

알려진 문제로 인해 Amazon S3에 최대 파일 크기가 5 GB인 파일만 업로드할 수 있습니다.

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=<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

속성	유형	필수	설명
`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 인코딩된 경로.

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": "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": []
}

참고: 최대 가져오기 파일 크기는 관리자가 설정할 수 있습니다. 기본값은 0(무제한)입니다. 관리자는 최대 가져오기 파일 크기를 수정할 수 있습니다. 그렇게 하려면 애플리케이션 설정 API 또는 관리자 영역에서 max_import_size 옵션을 사용하십시오.

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

Status: Beta

셀프 관리형 GitLab에서는 기본적으로 이 기능이 제공됩니다. 기능을 숨기려면 관리자가 기능 플래그 비활성화 할 수 있습니다. 이름은 import_project_from_remote_file입니다.
GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 있습니다.

POST /projects/remote-import

속성	유형	필수	설명
`path`	string	예	새 프로젝트의 이름과 경로입니다.
`url`	string	예	가져올 파일의 URL입니다.
`name`	string	아니요	가져올 프로젝트의 이름입니다. 제공되지 않으면 기본적으로 프로젝트의 경로를 사용합니다.
`namespace`	integer or string	아니요	프로젝트를 가져올 네임스페이스의 ID 또는 경로입니다. 현재 사용자의 네임스페이스가 기본값입니다.
`overwrite`	boolean	아니요	가져오기 시 동일한 경로의 프로젝트를 덮어쓸지 여부입니다. 기본값은 `false`입니다.
`override_params`	Hash	아니요	Project 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이어야 합니다.

단일 관계 가져오기

도입됨 GitLab 16.11에서 베타로, 플래그와 함께 이름은 single_relation_import. 기본적으로 비활성화되어 있습니다.

GitLab.com, 셀프 관리형 및 Dedicated에서 활성화됨 17.1에서.

이 엔드포인트는 프로젝트 내보내기 아카이브와 이름이 지정된 관계(문제, 병합 요청, 파이프라인 또는 마일스톤)를 수락하고 해당 관계를 다시 가져오며 이미 가져온 항목은 건너뜁니다.

필요한 프로젝트 내보내기 파일은 파일 가져오기에서 설명한 동일한 구조 및 크기 요구 사항을 준수합니다.

추출된 파일은 GitLab 프로젝트 내보내기 구조를 준수해야 합니다.
아카이브는 관리자가 구성한 최대 가져오기 파일 크기를 초과해서는 안 됩니다.

POST /projects/import-relation

속성	유형	필수	설명
`file`	string	예	업로드할 파일입니다.
`path`	string	예	새 프로젝트의 이름과 경로입니다.
`relation`	string	예	가져올 관계의 이름입니다. `issues`, `milestones`, `ci_pipelines` 또는 `merge_requests` 중 하나여야 합니다.

파일 시스템에서 파일을 업로드하려면 --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" \
     "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

속성	유형	필수	설명
`id`	정수 또는 문자열	예	프로젝트의 ID 또는 URL 인코딩 경로.

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "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 제거됨.

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": "<당신의 S3 리전 이름>",
  "bucket_name": "<당신의 S3 버킷 이름>",
  "file_key": "<당신의 S3 파일 키>",
  "access_key_id": "<당신의 AWS 액세스 키 ID>",
  "secret_access_key": "<당신의 AWS 비밀 액세스 키>"
}'

이 예는 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 배열에는 가져오기에 실패한 관계의 발생이 포함될 수 있습니다:

복구할 수 없는 오류.
재시도가 소진되었습니다. 일반적인 예: 쿼리 타임아웃.

참고: 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
    }
  }
}

On this page

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

전제 조건

내보내기 예약

내보내기 상태

내보내기 다운로드

파일 가져오기

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

단일 관계 가져오기

관계 가져오기 상태 확인

AWS S3에서 파일 가져오기

가져오기 상태

관련 주제

도움말

기능 사용 가능성과 제품 평가판

도움받기

On this page