리포지터리 API

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

리포지터리 트리 디렉터리

  • 숫자(?page=2)를 사용한 결과 페이지 반복 deprecated GitLab 14.3에서 삭제됨.

프로젝트의 파일과 디렉터리 디렉터리을 가져옵니다. 이 엔드포인트는 리포지터리가 공개적으로 접근 가능한 경우 인증 없이 액세스할 수 있습니다.

이 명령은 본질적으로 git ls-tree 명령어와 동일한 기능을 제공합니다. 자세한 정보는 Git 내부 문서의 트리 오브젝트 섹션을 참조하십시오.

caution
이 엔드포인트는 GitLab 15.0에서 키셋 기반 페이지네이션으로 변경되었습니다. 숫자(?page=2)를 사용하여 결과 페이지를 반복하는 것은 지원되지 않습니다.
GET /projects/:id/repository/tree

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path
page_token 문자열 아니오 다음 페이지를 가져올 트리 레코드 ID. 키셋 페이지네이션과 함께 사용됩니다.
pagination 문자열 아니오 keyset인 경우 키셋 기반 페이지네이션 방법 사용
path 문자열 아니오 리포지터리 내부 경로. 하위 디렉터리 내용을 가져오는 데 사용됩니다.
per_page 정수 아니오 페이지당 표시할 결과 수. 지정하지 않으면 기본값은 20입니다. 자세한 내용은 페이지네이션을 참조하십시오.
recursive 부울값 아니오 재귀 트리를 가져오는 데 사용되는 부울값. 기본값은 false입니다.
ref 문자열 아니오 리포지터리 브랜치 또는 태그의 이름 또는 지정하지 않은 경우 기본 브랜치. 
[
  {
    "id": "a1e8f8d745cc87e3a9248358d9352bb7f9a0aeba",
    "name": "html",
    "type": "tree",
    "path": "files/html",
    "mode": "040000"
  },
  {
    "id": "4535904260b1082e14f867f7a24fd8c21495bde3",
    "name": "images",
    "type": "tree",
    "path": "files/images",
    "mode": "040000"
  },
  {
    "id": "31405c5ddef582c5a9b7a85230413ff90e2fe720",
    "name": "js",
    "type": "tree",
    "path": "files/js",
    "mode": "040000"
  },
  {
    "id": "cc71111cfad871212dc99572599a568bfe1e7e00",
    "name": "lfs",
    "type": "tree",
    "path": "files/lfs",
    "mode": "040000"
  },
  {
    "id": "fd581c619bf59cfdfa9c8282377bb09c2f897520",
    "name": "markdown",
    "type": "tree",
    "path": "files/markdown",
    "mode": "040000"
  },
  {
    "id": "23ea4d11a4bdd960ee5320c5cb65b5b3fdbc60db",
    "name": "ruby",
    "type": "tree",
    "path": "files/ruby",
    "mode": "040000"
  },
  {
    "id": "7d70e02340bac451f281cecf0a980907974bd8be",
    "name": "whitespace",
    "type": "blob",
    "path": "files/whitespace",
    "mode": "100644"
  }
]

리포지터리에서 블롭 가져오기

리포지터리의 블롭에 대한 크기 및 내용과 같은 정보를 받을 수 있습니다. 블롭 내용은 Base64로 인코딩됩니다. 이 엔드포인트는 리포지터리가 공개적으로 접근 가능한 경우 인증 없이 액세스할 수 있습니다. 

GET /projects/:id/repository/blobs/:sha

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path
sha 문자열 예 블롭 SHA.

원시 블롭 내용

블롭 SHA로부터 블롭의 원시 파일 내용을 가져옵니다. 이 엔드포인트는 리포지터리가 공개적으로 접근 가능한 경우 인증 없이 액세스할 수 있습니다. 

GET /projects/:id/repository/blobs/:sha/raw

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path
sha 문자열 예 블롭 SHA.

파일 아카이브 가져오기

리포지터리의 아카이브를 가져옵니다. 이 엔드포인트는 리포지터리가 공개적으로 접근 가능한 경우 인증 없이 액세스할 수 있습니다.

GitLab.com 사용자를 위해, 이 엔드포인트는 분당 5개의 요청에 대한 요청 제한 임계값을 가지고 있습니다. 

GET /projects/:id/repository/archive[.format]

format은 아카이브 형식을 위한 선택적 접미사이며 기본값은 tar.gz입니다. 예를 들어, archive.zip을 지정하면 ZIP 형식의 아카이브를 보냅니다. 사용 가능한 옵션은 다음과 같습니다:

  • bz2
  • tar
  • tar.bz2
  • tar.gz
  • tb2
  • tbz
  • tbz2
  • zip

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path
path 문자열 아니오 다운로드할 리포지터리의 하위 경로. 빈 문자열인 경우 전체 리포지터리로 기본 설정됩니다.
sha 문자열 아니오 다운로드할 커밋 SHA. 태그, 브랜치 참조 또는 SHA를 사용할 수 있습니다. 지정하지 않으면 기본 브랜치의 최상위로 기본 설정됩니다.

예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>&path=<path>"

브랜치, 태그 또는 커밋 비교하기

이 엔드포인트는 리포지터리가 공개적으로 접근 가능한 경우 인증 없이 액세스할 수 있습니다. 차이점이 있는 경우 빈 차이 문자열이 될 수 있습니다. 차이 한계에 도달한 경우 차이가 비어있을 수 있습니다. 

GET /projects/:id/repository/compare

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path
from 문자열 예 커밋 SHA 또는 브랜치 이름
to 문자열 예 커밋 SHA 또는 브랜치 이름
from_project_id 정수 아니오 비교 원본 ID
straight 부울값 아니오 비교 방법: true는 from과 to 사이의 직접 비교(from..to), false는 Merge 기준을 사용한 비교 (from…to)입니다. 기본값은 false입니다.
unidiff 부울값 아니오 통합된 차이 형식으로 차이를 표시합니다. 기본값은 false입니다. GitLab 16.5에서 도입되었습니다. 
GET /projects/:id/repository/compare?from=main&to=feature

예시 응답: 

{
  "commit": {
    "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
    "short_id": "12d65c8dd2b",
    "title": "JS fix",
    "author_name": "Example User",
    "author_email": "user@example.com",
    "created_at": "2014-02-27T10:27:00+02:00"
  },
  "commits": [{
    "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
    "short_id": "12d65c8dd2b",
    "title": "JS fix",
    "author_name": "Example User",
    "author_email": "user@example.com",
    "created_at": "2014-02-27T10:27:00+02:00"
  }],
  "diffs": [{
    "old_path": "files/js/application.js",
    "new_path": "files/js/application.js",
    "a_mode": null,
    "b_mode": "100644",
    "diff": "@@ -24,8 +24,10 @@\n //= require g.raphael-min\n //= require g.bar-min\n //= require branch-graph\n-//= require highlightjs.min\n-//= require ace/ace\n //= require_tree .\n //= require d3\n //= require underscore\n+\n+function fix() { \n+  alert(\"Fixed\")\n+}",
    "new_file": false,
    "renamed_file": false,
    "deleted_file": false
  }],
  "compare_timeout": false,
  "compare_same_ref": false,
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/compare/ae73cb07c9eeaf35924a10f713b364d32b2dd34f...0b4bc9a49b562e85de7cc9e834518ea6828729b9"
}

기여자

리포지터리 기여자 디렉터리을 가져옵니다. 리포지터리가 공개적으로 접근 가능한 경우에는 인증 없이 이 엔드포인트에 접근할 수 있습니다. 

GET /projects/:id/repository/contributors

지원되는 속성:

속성 타입 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL-encoded path
order_by 문자열 아니오 name, email, 또는 commits (커밋 날짜 순) 필드로 기여자를 정렬하여 반환합니다. 기본값은 commits입니다.
sort 문자열 아니오 기여자를 asc 또는 desc 순으로 정렬하여 반환합니다. 기본값은 asc입니다.

예시 응답: 

[{
  "name": "Example User",
  "email": "example@example.com",
  "commits": 117,
  "additions": 0,
  "deletions": 0
}, {
  "name": "Sample User",
  "email": "sample@example.com",
  "commits": 33,
  "additions": 0,
  "deletions": 0
}]

합병 베이스

커밋 SHA, 브랜치 이름 또는 태그와 같은 2개 이상의 참조에 대한 공통 조상을 가져옵니다. 

GET /projects/:id/repository/merge_base
속성 타입 필수 설명
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL-encoded path.
refs 배열 예 공통 조상을 찾을 참조입니다. 여러 참조를 허용합니다.

가독성을 위해 참조가 생략된 예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/5/repository/merge_base?refs[]=304d257d&refs[]=0031876f"

예시 응답: 

{
  "id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
  "short_id": "1a0b36b3",
  "title": "Initial commit",
  "created_at": "2014-02-27T08:03:18.000Z",
  "parent_ids": [],
  "message": "Initial commit\n",
  "author_name": "Example User",
  "author_email": "user@example.com",
  "authored_date": "2014-02-27T08:03:18.000Z",
  "committer_name": "Example User",
  "committer_email": "user@example.com",
  "committed_date": "2014-02-27T08:03:18.000Z"
}

변경 로그 데이터를 변경 로그 파일에 추가

리포지터리의 커밋을 기반으로 변경 로그 데이터를 생성합니다.

특정 의미론적 버전 및 커밋 범위가 주어지면 GitLab은 특정 Git 트레일러를 사용하는 모든 커밋에 대한 변경 로그를 생성합니다. GitLab은 프로젝트의 Git 리포지터리에 새로운 Markdown 형식의 섹션을 추가합니다. 출력 형식은 사용자 정의할 수 있습니다.

사용자를 위한 문서는 변경 로그를 참조하십시오. 

POST /projects/:id/repository/changelog

지원되는 속성

변경 로그는 다음 속성을 지원합니다:

속성 타입 필수 설명
version 문자열 예 변경 로그를 생성할 버전. 형식은 의미론적 버전을 따라야 합니다.
branch 문자열 아니오 변경 로그 변경 사항을 커밋할 브랜치. 프로젝트의 기본 브랜치를 기본값으로 사용합니다.
config_file 문자열 아니오 프로젝트의 Git 리포지터리의 변경 로그 구성 파일 경로. 기본값은 .gitlab/changelog_config.yml입니다.
date 날짜 및 시간 아니오 릴리스의 날짜와 시간. 기본값은 현재 시간입니다.
file 문자열 아니오 변경 사항을 커밋할 파일. 기본값은 CHANGELOG.md입니다.
from 문자열 아니오 변경 로그에 포함할 커밋 범위의 시작점 커밋의 SHA. 이 커밋은 변경 로그에 포함되지 않습니다.
message 문자열 아니오 변경 사항을 커밋할 때 사용할 커밋 메시지. 기본값은 Add changelog for version X이며, 여기서 X는 version 인수의 값입니다.
to 문자열 아니오 변경 로그에 포함할 커밋 범위의 끝 지점 커밋의 SHA. 이 커밋은 변경 로그에 포함됩니다. 기본값은 branch 속성에서 지정된 브랜치입니다. 피처 플래그 changelog_commits_limitation이 비활성화되지 않은 경우, 최대 15000개의 커밋까지 제한됩니다.
trailer 문자열 아니오 커밋을 포함하기 위해 사용할 Git 트레일러. 기본값은 Changelog입니다. 대소문자를 구분합니다. Example은 example 또는 eXaMpLE과 일치하지 않습니다.

from 속성 요구 사항

from 속성이 지정되지 않은 경우, GitLab은 version 속성에 지정된 버전보다 앞서는 마지막 안정적인 버전의 Git 태그를 사용합니다. GitLab이 태그 이름에서 버전 번호를 추출하려면 Git 태그 이름이 특정 형식을 따라야 합니다. 기본적으로 GitLab은 다음과 같은 형식의 태그를 고려합니다:

  • vX.Y.Z
  • X.Y.Z

여기서 X.Y.Z는 의미론적 버전을 따릅니다.

예를 들어 다음과 같은 태그를 가진 프로젝트를 고려해 보십시오:

  • v1.0.0-pre1
  • v1.0.0
  • v1.1.0
  • v2.0.0

version 속성이 2.1.0인 경우, GitLab은 태그 v2.0.0을 사용합니다. 그리고 버전이 1.1.1 또는 1.2.0인 경우, GitLab은 태그 v1.1.0을 사용합니다. 프리 릴리스 태그는 무시되므로 태그 v1.0.0-pre1는 사용되지 않습니다. version 속성은 v로 시작할 수 있습니다. 예를 들어: v1.0.0. 이 경우 응답은 version 값 1.0.0일 때와 동일합니다. GitLab 17.0에서 도입되었습니다.

from이 지정되지 않고 사용할 태그가 없는 경우 API는 오류를 생성합니다. 해당 오류를 해결하려면 from 속성에 명시적인 값을 지정해야 합니다.

매뉴얼으로 관리되는 변경 로그 파일에서 Git 트레일러를 사용한 변경 로그 파일로 마이그레이션

기존 매뉴얼으로 관리되는 변경 로그 파일에서 Git 트레일러를 사용하는 변경 로그 파일로 마이그레이션할 때, 변경 로그 파일이 기대 형식과 일치하도록 확인하십시오. 그렇지 않으면 API에서 추가되는 새 변경 로그 항목이 예상치 않은 위치에 삽입될 수 있습니다. 예를 들어, 매뉴얼으로 관리되는 변경 로그 파일의 버전 값이 vX.Y.Z로 지정된 경우, Git 트레일러를 사용하여 추가된 새 변경 로그 항목이 변경 로그 파일의 끝에 추가됩니다.

Issue 444183에서 변경 로그 파일의 버전 헤더 형식을 사용자 정의하는 것을 제안합니다. 그러나 해당 이슈가 완료되기 전까지 변경 로그 파일에서 예상되는 버전 헤더 형식은 X.Y.Z입니다.

예시

이러한 예시들은 cURL을 사용하여 HTTP 요청을 수행합니다. 예시 명령어는 다음과 같은 값을 사용합니다:

  • 프로젝트 ID: 42
  • 위치: GitLab.com에 호스팅됨
  • 예시 API 토큰: token

이 명령은 1.0.0 버전용 변경 로그를 생성합니다.

커밋 범위:

  • 마지막 릴리스 태그로 시작합니다.
  • 대상 브랜치에서의 마지막 커밋으로 끝납니다. 기본 대상 브랜치는 프로젝트의 기본 브랜치입니다.

만약 마지막 태그가 v0.9.0이고, 기본 브랜치가 main이라면, 이 예시에 포함된 커밋 범위는 v0.9.0..main입니다: 

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog"

다른 브랜치에서 데이터를 생성하려면 branch 매개변수를 지정하세요. 이 명령은 foo 브랜치에서 데이터를 생성합니다: 

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog"

다른 트레일러를 사용하려면 trailer 매개변수를 사용하세요: 

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog"

결과를 다른 파일에 저장하려면 file 매개변수를 사용하세요: 

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog"

변경 로그 데이터 생성

리포지터리의 커밋을 기반으로 변경 로그 데이터를 생성하되, 변경 로그 파일에는 커밋하지 않습니다.

POST /projects/:id/repository/changelog와 정확히 같이 작동하지만, 변경 로그 데이터는 어떤 변경 로그 파일에도 커밋되지 않습니다. 

GET /projects/:id/repository/changelog

지원되는 속성:

속성 유형 필수 여부 설명
version string yes 변경 로그를 생성할 버전입니다. 포맷은 semantic versioning을 따라야 합니다.
config_file string no 프로젝트의 Git 리포지터리에 있는 변경 로그 구성 파일의 경로입니다. 기본값은 .gitlab/changelog_config.yml입니다.
date datetime no 릴리스의 날짜와 시간입니다. ISO 8601 형식을 사용합니다. 예: 2016-03-11T03:45:40Z. 기본값은 현재 시간입니다.
from string no 변경 로그를 생성하는 데 사용할 커밋 범위의 시작지점(SHA)입니다. 이 커밋 자체는 디렉터리에 포함되지 않습니다.
to string no 변경 로그를 생성하는 데 사용할 커밋 범위의 끝지점(SHA)입니다. 이 커밋은 디렉터리에 포함됩니다. 기본값은 기본 프로젝트 브랜치의 HEAD입니다.
trailer string no 커밋을 포함할 때 사용할 Git 트레일러입니다. 기본값은 Changelog입니다. 
curl --header "PRIVATE-TOKEN: token" \
  "https://gitlab.com/api/v4/projects/42/repository/changelog?version=1.0.0"

예시 응답, 가독성을 위해 줄 바꿈 추가: 

{
  "notes": "## 1.0.0 (2021-11-17)\n\n### feature (2 changes)\n\n-
    [Title 2](namespace13/project13@ad608eb642124f5b3944ac0ac772fecaf570a6bf)
    ([merge request](namespace13/project13!2))\n-
    [Title 1](namespace13/project13@3c6b80ff7034fa0d585314e1571cc780596ce3c8)
    ([merge request](namespace13/project13!1))\n"
}

관련 주제