전제 조건
내보내기 예약
내보내기 상태
내보내기 다운로드
파일 가져오기
원격 객체 리포지터리에서 파일 가져오기
단일 관계 가져오기
관계 가져오기 상태 확인
AWS S3에서 파일 가져오기
가져오기 상태
관련 주제

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

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

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

프로젝트 가져오기 및 내보내기 API를 사용하기 전에, group import and export API를 사용하는 것이 좋습니다.

프로젝트 가져오기 및 내보내기 API를 사용한 후에, 프로젝트 레벨 CI/CD 변수 API를 사용할 수 있습니다.

컨테이너 레지스트리를 여전히 Docker 풀 및 푸시의 일련의 프로세스를 통해 마이그레이션해야 합니다. 어떠한 빌드 아티팩트도 검색하기 위해 CI/CD 파이프라인을 재실행하세요.

전제 조건

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

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

내보내기 예약

새로운 내보내기를 시작합니다.

이 엔드포인트는 upload 해시 파라미터도 허용합니다. 이는 내보낸 프로젝트를 웹 서버나 S3 호환 플랫폼에 업로드하기 위한 모든 필수 정보를 포함합니다. GitLab은 내보내기에 대해서 다음을 지원합니다:

최종 서버로의 이진 데이터 파일 업로드만 지원됩니다.
업로드 요청에 Content-Type: application/gzip 헤더를 보냅니다. 사전 서명된 URL에 이를 서명의 일부로 포함해야 합니다.
프로젝트 내보내기 프로세스를 완료하는 데 시간이 소요될 수 있습니다. 업로드 URL이 짧은 만료 시간을 가지지 않고, 내보내기 프로세스 중에 계속해서 사용 가능한지 확인하십시오.
관리자는 최대 내보내기 파일 크기를 수정할 수 있습니다. 기본적으로 최대 크기는 무제한(0)입니다. 이를 변경하려면 다음 중 하나를 사용하여 max_export_size를 편집하십시오:
- GitLab UI
- Application settings API
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 인코딩된 경로

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에서 도입된 개발자 역할 대신 유지자 역할이 필요합니다. (16.0은 뒤쪽으로 백포트되었음)

POST /projects/import

속성	유형	필수	설명
`file`	문자열	예	업로드할 파일
`path`	문자열	예	새 프로젝트의 이름과 경로
`name`	문자열	아니요	가져올 프로젝트의 이름. 제공되지 않으면 기본적으로 프로젝트 경로로 설정됩니다.
`namespace`	정수 또는 문자열	아니요	프로젝트를 가져올 네임스페이스의 ID 또는 경로. 현재 사용자의 네임스페이스로 기본 설정됩니다. 가져올 대상 그룹에서 적어도 유지자 역할이 필요합니다.
`override_params`	해시	아니요	내보내기 파일 내에서 정의된 모든 값을 지원합니다.
`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(무제한)입니다. 관리자로서 최대 가져오기 파일 크기를 수정할 수 있습니다. 이를 위해 Application settings API나 관리자 영역에서 max_import_size 옵션을 사용하십시오.

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

Status: Beta

Self-Managed GitLab의 경우, 기본적으로 이 기능을 사용할 수 있습니다. 기능을 숨기려면 관리자가 import_project_from_remote_file라는 피처 플래그를 비활성화할 수 있습니다. GitLab.com 및 GitLab Dedicated의 경우, 이 기능을 사용할 수 있습니다.

POST /projects/remote-import

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

단일 관계 가져오기

GitLab 16.11에서 Beta)에서 도입됨), Flag이 single_relation_import로 지정되어 비활성화됨.

이 엔드포인트는 프로젝트 내보내기 아카이브 및 지정된 관계 (이슈, Merge Request, 파이프라인 또는 마일스톤)를 받아들이고, 이미 가져온 항목은 건너뛰며 해당 관계를 다시 가져옵니다.

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

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

POST /projects/import-relation

속성	유형	필수	설명
`file`	string	yes	업로드될 파일.
`path`	string	yes	새 프로젝트의 이름과 경로.
`relation`	string	yes	가져올 관계의 이름. `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`	integer 또는 string	yes	프로젝트의 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`	string	yes	AWS S3 액세스 키 ID.
`bucket_name`	string	yes	AWS S3 버킷 이름. 파일이 저장된 위치.
`file_key`	string	yes	파일을 식별하는 AWS S3 파일 키.
`path`	string	yes	새 프로젝트의 전체 경로.
`region`	string	yes	파일이 저장된 AWS S3 지역 이름.
`secret_access_key`	string	yes	AWS S3 비밀 액세스 키.
`name`	string	no	가져올 프로젝트의 이름. 제공되지 않은 경우, 경로로 기본 설정됩니다.
`namespace`	integer 또는 string	no	가져올 프로젝트를 가져올 네임스페이스의 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": "Sample Project",
  "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 버킷에서 가져오는데 사용되는 모듈을 사용합니다:

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": "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

속성	유형	필수	설명
`id`	integer 또는 string	예	인증된 사용자가 소유한 프로젝트의 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
    }
  }
}

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

전제 조건

내보내기 예약

내보내기 상태

내보내기 다운로드

파일 가져오기

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

단일 관계 가져오기

관계 가져오기 상태 확인

AWS S3에서 파일 가져오기

가져오기 상태

관련 주제

도움말

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

도움받기