레포지토리 API

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

레포지토리 트리 목록

  • 결과의 페이지를 반복하는 것(?page=2)은 GitLab 14.3에서 사용 중단됨.

프로젝트의 레포지토리 파일 및 디렉터리 목록을 가져옵니다. 이 엔드포인트는 레포지토리가 공개적으로 접근 가능하면 인증 없이 접근할 수 있습니다.

이 명령은 본질적으로 git ls-tree 명령과 동일한 기능을 제공합니다. 더 많은 정보는 Git 내부 문서의 트리 객체 섹션을 참조하세요.

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

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL-인코딩된 경로.
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"
  }
]

저장소에서 Blob 가져오기

저장소 내 Blob에 대한 정보(크기 및 내용 등)를 수신할 수 있습니다.

Blob 내용은 Base64로 인코딩됩니다. 이 엔드포인트는 인증 없이 접근할 수 있으며,

저장소가 공개적으로 접근 가능한 경우에 해당합니다.

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

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로입니다.
sha 문자열 예 Blob SHA입니다.

원시 Blob 내용

Blob SHA를 통해 Blob의 원시 파일 내용을 가져옵니다. 이 엔드포인트는 인증 없이 접근할 수 있습니다.

저장소가 공개적으로 접근 가능한 경우에 해당합니다.

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

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로입니다.
sha 문자열 예 Blob 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 인코딩된 경로입니다.
path 문자열 아니오 다운로드할 저장소의 하위 경로입니다. 빈 문자열이면 전체 저장소를 기본으로 합니다.
sha 문자열 아니오 다운로드할 커밋 SHA입니다. 태그, 브랜치 참조 또는 SHA를 사용할 수 있습니다. 지정하지 않으면 기본 브랜치의 가장 끝을 기본으로 합니다.

예시 요청:

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

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

이 엔드포인트는 인증 없이 접근할 수 있으며, 저장소가

공식적으로 접근 가능한 경우에 해당합니다. 차이가 diff limits에 도달하면 빈 diff 문자열을 가질 수 있습니다.

GET /projects/:id/repository/compare

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로입니다.
from 문자열 예 커밋 SHA 또는 브랜치 이름입니다.
to 문자열 예 커밋 SHA 또는 브랜치 이름입니다.
from_project_id 정수 아니오 비교할 ID입니다.
straight 불리언 아니오 비교 방법: from과 to 간의 직접 비교를 위해 true(/from..to), 가장 머지된 기준을 사용하여 비교하기 위해 false(/from…to)입니다. 기본값은 false입니다.
unidiff 불리언 아니오 통합 diff 형식으로 차이를 표시합니다. 기본값은 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 integer 또는 string 예 프로젝트의 ID 또는 URL-인코딩된 경로입니다.
ref string 아니오 저장소 브랜치 또는 태그의 이름입니다. 주어지지 않으면 기본 브랜치입니다.
order_by string 아니오 name, email, 또는 commits (커밋 날짜 기준) 필드에 따라 정렬된 기여자를 반환합니다. 기본은 commits입니다.
sort string 아니오 asc 또는 desc 순서로 정렬된 기여자를 반환합니다. 기본은 asc입니다.

예제 요청:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/7/repository/contributors"

예제 응답:

[{
  "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개 이상의 refs의 공통 조상을 가져옵니다.

GET /projects/:id/repository/merge_base
속성 유형 필수 설명
id integer 또는 string 예 프로젝트의 ID 또는 URL-인코딩된 경로입니다.
refs array 예 공통 조상을 찾기 위한 refs입니다. 여러 refs를 허용합니다.

예제 요청, 가독성을 위해 refs가 생략되었습니다:

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

예제 응답:

{
  "id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
  "short_id": "1a0b36b3",
  "title": "초기 커밋",
  "created_at": "2014-02-27T08:03:18.000Z",
  "parent_ids": [],
  "message": "초기 커밋\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"
}

changelog 데이터를 changelog 파일에 추가하기

저장소의 커밋을 기반으로 changelog 데이터를 생성합니다.

의미 있는 버전과 커밋 범위를 고려할 때, GitLab은 특정 Git 트레일러를 사용하는 모든 커밋에 대해 changelog를 생성합니다. GitLab은 프로젝트의 Git 저장소에 있는 changelog 파일에 새로운 Markdown 형식 섹션을 추가합니다. 출력 형식은 사용자 맞춤형으로 설정할 수 있습니다.

사용자 문서에 대한 내용은 Changelogs를 참조하세요.

POST /projects/:id/repository/changelog

지원되는 속성

Changelogs는 다음 속성을 지원합니다:

속성 유형 필수 설명
version 문자열 예 changelog를 생성할 버전. 형식은 의미 있는 버전 체계를 따라야 합니다.
branch 문자열 아니오 changelog 변경 사항을 커밋할 브랜치. 기본적으로 프로젝트의 기본 브랜치입니다.
config_file 문자열 아니오 프로젝트의 Git 저장소에 있는 changelog 구성 파일의 경로. 기본적으로 .gitlab/changelog_config.yml입니다.
date 날짜시간 아니오 릴리스의 날짜 및 시간. 기본적으로 현재 시간입니다.
file 문자열 아니오 변경 사항을 커밋할 파일. 기본적으로 CHANGELOG.md입니다.
from 문자열 아니오 changelog에 포함할 커밋 범위의 시작을 표시하는 커밋의 SHA. 이 커밋은 changelog에 포함되지 않습니다.
message 문자열 아니오 변경 사항을 커밋할 때 사용할 커밋 메시지. 기본적으로 버전 X의 changelog 추가입니다. 여기서 X는 version 인수의 값입니다.
to 문자열 아니오 changelog에 포함할 커밋 범위의 끝을 표시하는 커밋의 SHA. 이 커밋은 changelog에 포함됩니다. 기본적으로 branch 속성에 지정된 브랜치입니다. 최대 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을 사용합니다. version이 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로 지정된 경우

X.Y.Z 대신에는, Git 트레일러를 사용하여 추가된 새로운 변경 로그 항목이

변경 로그 파일의 끝에 추가됩니다.

문제 444183는 변경 로그 파일에서 버전 헤더 형식을 사용자 정의하는 것을 제안합니다.

그러나 해당 문제가 완료될 때까지 변경 로그 파일의 예상 버전 헤더 형식은 X.Y.Z입니다.

예시

이러한 예시는 HTTP 요청을 수행하기 위해 cURL을 사용합니다.

예제 명령은 다음 값들을 사용합니다:

  • 프로젝트 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" \
  --url "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" \
  --url "https://gitlab.com/api/v4/projects/42/repository/changelog"

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

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

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

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

변경 로그 데이터 생성

변경 로그 파일에 커밋하지 않고 저장소의 커밋을 기반으로 변경 로그 데이터를 생성합니다.

POST /projects/:id/repository/changelog와 정확히 동일하게 작동하지만,

변경 로그 데이터는 어떤 변경 로그 파일에도 커밋되지 않습니다.

GET /projects/:id/repository/changelog

지원되는 속성:

속성 유형 필수 설명
version string 예 변경 로그를 생성할 버전입니다. 형식은 시맨틱 버전을 따라야 합니다.
config_file string 아니요 프로젝트의 Git 저장소에 있는 변경 로그 구성 파일의 경로입니다. 기본값은 .gitlab/changelog_config.yml입니다.
date datetime 아니요 릴리스의 날짜와 시간입니다. ISO 8601 형식을 사용합니다. 예: 2016-03-11T03:45:40Z. 기본값은 현재 시간입니다.
from string 아니요 변경 로그 생성을 위해 사용할 커밋의 범위 시작 부분(SHA로)입니다. 이 커밋 자체는 목록에 포함되지 않습니다.
to string 아니요 변경 로그에 사용할 커밋의 범위 끝부분(인클루드 SHA로)입니다. 이 커밋은 목록에 포함됩니다. 기본값은 기본 프로젝트 브랜치의 HEAD입니다.
trailer string 아니요 커밋 포함에 사용할 Git 트레일러입니다. 기본값은 Changelog입니다. 
curl --header "PRIVATE-TOKEN: token" \
  --url "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"
}

관련 주제