리포지터리 트리 디렉터리
리포지터리에서 블롭 가져오기
Raw 블롹 내용
파일 아카이브 가져오기
브랜치, 태그 또는 커밋 비교
기여자
머지 베이스
변경 로그 파일에 변경 로그 데이터 추가
변경 로그 데이터 생성
관련 주제

리포지터리 API

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

리포지터리 트리 디렉터리

번호로 결과 페이지를 반복 (?page=2) 비권장됨 - GitLab 14.3에서 제거되었습니다.

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

이 명령은 기본적으로 git ls-tree 명령어와 동일한 기능을 제공합니다. 자세한 내용은 Git 내부 문서의 트리 객체 섹션을 참조하세요.

이 엔드포인트는 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"
  }
]

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

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

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

지원되는 속성:

속성	유형	필수	설명
`id`	정수 또는 문자열	예	인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩 된 경로입니다.
`sha`	문자열	예	블롭 SHA입니다.

Raw 블롹 내용

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

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

지원되는 속성:

속성	유형	필수	설명
`id`	정수 또는 문자열	예	인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩 된 경로입니다.
`sha`	문자열	예	블롭 SHA입니다.

파일 아카이브 가져오기

Git LFS 블롭 포함을 지원하는 것은 GitLab 13.5에서 도입되었습니다.
서브폴더 다운로드 지원은 GitLab 14.4에서 도입되었습니다.

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

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>" \
  "https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>&path=<path>"

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

이 엔드포인트는 리포지터리가 공개적으로 접근 가능한 경우 인증 없이 액세스할 수 있습니다. Diff에 대해 diff 제한이 도달되면 빈 diff 문자열을 가질 수 있습니다.

GET /projects/:id/repository/compare

지원되는 속성:

속성	유형	필수	설명
`id`	정수 또는 문자열	예	인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로
`from`	문자열	예	커밋 SHA 또는 브랜치 이름
`to`	문자열	예	커밋 SHA 또는 브랜치 이름
`from_project_id`	정수	아니오	비교 대상 ID
`straight`	부울	아니오	비교 방법: `true`는 `from`과 `to` 사이의 직접 비교 (`from`..`to`)를, `false`는 머지 베이스를 사용한 비교 (`from`…`to`)를 나타냅니다. 기본값은 `false`입니다.
`unidiff`	부울	아니오	통합된 diff 형식으로 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"
}

기여자

속성 additions 및 deletions은 GitLab 13.4에서 폐기되었습니다. 왜냐하면 항상 0을 반환했기 때문에 이를 반환합니다.
속성 additions 및 deletions은 GitLab 14.0에서 삭제되었습니다.

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

GET /projects/:id/repository/contributors

지원되는 속성:

속성	유형	필수	설명
`id`	정수 또는 문자열	예	인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로
`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`	정수 또는 문자열	예	URL 인코딩된 경로의 ID 또는 해당 프로젝트의 ID
`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": "초기 커밋",
  "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"
}

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

GitLab 13.9에서 도입되었습니다.
커밋 범위 제한은 GitLab 15.1에서 changelog_commits_limitation이라는 플래그로 소개되었습니다. 기본적으로 활성화됩니다.

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

의미 있는 버전 및 일련의 커밋이 주어지면 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`	문자열	아니오	변경 사항을 커밋할 때 사용할 커밋 메시지. `version` 인수의 값이 `X`인 경우 기본값은 `version X에 대한 변경 로그 추가`입니다.
`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 16.10에서 도입되었습니다.

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

매뉴얼으로 관리되는 변경 로그 파일에서 Git 트레일러를 사용하는 방법

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

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

변경 로그 데이터 생성

GitLab 14.6에서 도입되었습니다.

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

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" \
  "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"
}

리포지터리 API

리포지터리 트리 디렉터리

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

Raw 블롹 내용

파일 아카이브 가져오기

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

기여자

머지 베이스

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

지원되는 속성

`from` 속성의 요구 사항

매뉴얼으로 관리되는 변경 로그 파일에서 Git 트레일러를 사용하는 방법

예시

변경 로그 데이터 생성

관련 주제

도움말

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

도움받기

리포지터리 API

리포지터리 트리 디렉터리

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

Raw 블롹 내용

파일 아카이브 가져오기

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

기여자

머지 베이스

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

지원되는 속성

from 속성의 요구 사항

매뉴얼으로 관리되는 변경 로그 파일에서 Git 트레일러를 사용하는 방법

예시

변경 로그 데이터 생성

관련 주제

도움말

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

도움받기

`from` 속성의 요구 사항