- 저장소 트리 목록
- 저장소에서 blob 가져오기
- Raw blob content
- Get file archive
- 브랜치, 태그 또는 커밋 비교
- 기여자들
- 병합 베이스
- 변경 로그 데이터를 변경 로그 파일에 추가
- 변경 로그 데이터 생성
- 관련 주제
저장소 API
저장소 트리 목록
- 숫자(
?page=2
)로 결과 페이지 반복 deprecated 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"
}
]
저장소에서 blob 가져오기
저장소의 blob에 대한 크기 및 내용과 같은 정보를 받을 수 있습니다. Blob 내용은 Base64로 인코딩됩니다. 이 엔드포인트는 저장소가 공개적으로 접근 가능한 경우 인증 없이 액세스할 수 있습니다.
GET /projects/:id/repository/blobs/:sha
지원되는 속성:
속성 | 유형 | 필요성 | 설명 |
---|---|---|---|
id
| 정수 또는 문자열 | 예 | 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로. |
sha
| 문자열 | 예 | blob SHA. |
Raw blob content
블롭의 SHA로 파일 내용을 가져옵니다. 이 엔드포인트는 저장소가 공개적으로 접근 가능한 경우에 인증 없이 액세스할 수 있습니다.
GET /projects/:id/repository/blobs/:sha/raw
지원되는 속성들:
속성 | 타입 | 필수 | 설명 |
---|---|---|---|
id
| 정수 또는 문자열 | 예 | 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로입니다. |
sha
| 문자열 | 예 | 블롭 SHA입니다. |
Get file archive
- Git LFS blobs를 포함한 경우의 서포트는 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>"
브랜치, 태그 또는 커밋 비교
이 엔드포인트는 저장소가 공개적으로 접근 가능한 경우에 인증 없이 액세스할 수 있습니다. Diffs는 diff limits에 도달하면 빈 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
| 부울 | 아니요 | diffs를 단일된 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
| 정수 또는 문자열 | 예 | 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로 |
order_by
| 문자열 | 아니오 |
name , email , 또는 commits (커밋 날짜별로 정렬) 필드에 따라 기여자를 정렬. 기본값은 commits 입니다.
|
sort
| 문자열 | 아니오 | 기여자를 asc 또는 desc 순서로 정렬합니다. 기본값은 asc 입니다.
|
예시 응답:
[{
"name": "예시 사용자",
"email": "example@example.com",
"commits": 117,
"additions": 0,
"deletions": 0
}, {
"name": "샘플 사용자",
"email": "sample@example.com",
"commits": 33,
"additions": 0,
"deletions": 0
}]
병합 베이스
커밋 SHA, 브랜치 이름 또는 태그와 같은 2개 이상의 참조에 대한 공통 조상을 가져옵니다.
GET /projects/:id/repository/merge_base
속성 | 타입 | 필수 | 설명 |
---|---|---|---|
id
| 정수 또는 문자열 | 예 | URL 인코딩된 경로의 프로젝트 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": "예시 사용자",
"author_email": "user@example.com",
"authored_date": "2014-02-27T08:03:18.000Z",
"committer_name": "예시 사용자",
"committer_email": "user@example.com",
"committed_date": "2014-02-27T08:03:18.000Z"
}
변경 로그 데이터를 변경 로그 파일에 추가
저장소의 커밋을 기반으로 변경 로그 데이터를 생성합니다.
의미적 버전과 커밋 범위가 주어지면, GitLab은 특정 Git 트레일러를 사용하는 모든 커밋에 대한 변경 로그를 생성하여 프로젝트의 Git 저장소에 있는 변경 로그 파일에 새로운 Markdown 형식의 섹션을 추가합니다. 출력 형식은 사용자화할 수 있습니다.
사용자를 대상으로 한 문서에 대해서는 변경 로그를 참조하세요.
POST /projects/:id/repository/changelog
지원되는 속성
변경 로그는 이러한 속성을 지원합니다:
속성 | 타입 | 필수 | 설명 |
---|---|---|---|
version
| 문자열 | 예 | 변경 로그를 생성할 버전. 형식은 의미적 버전ing을 따라야 합니다. |
branch
| 문자열 | 아니오 | 변경 로그 변경 사항을 커밋할 브랜치. 프로젝트의 기본 브랜치로 기본 설정됩니다. |
config_file
| 문자열 | 아니오 | 프로젝트의 Git 저장소 내의 변경 로그 구성 파일 경로. 기본값은 .gitlab/changelog_config.yml 입니다.
|
date
| 날짜 및 시간 | 아니오 | 릴리스의 날짜와 시간. 기본값은 현재 시간입니다. |
file
| 문자열 | 아니오 | 변경 사항을 커밋할 파일. 기본값은 CHANGELOG.md 입니다.
|
from
| 문자열 | 아니오 | 변경 로그에 포함할 커밋 범위의 시작을 나타내는 커밋의 SHA. 이 커밋은 변경 로그에 포함되지 않습니다. |
message
| 문자열 | 아니오 | 변경 사항을 커밋할 때 사용할 커밋 메시지. 기본값은 version 인수의 값인 버전 X에 대한 변경 로그 추가 입니다.
|
to
| 문자열 | 아니오 | 변경 로그에 포함할 커밋 범위의 끝을 나타내는 커밋의 SHA. 이 커밋은 변경 로그에 포함됩니다. branch 속성에 지정된 브랜치로 기본값이 설정됩니다. changelog_commits_limitation 기능 플래그가 비활성화되어 있지 않은 한 15000개의 커밋으로 제한됩니다.
|
trailer
| 문자열 | 아니오 | 커밋을 포함하는 데 사용할 Git 트레일러. 기본값은 Changelog 입니다. 대소문자를 구분합니다: 예시 는 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
태그는 무시됩니다. 풀리퀘스트(Pre-release) 태그는 무시되기 때문입니다.
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
입니다.
예제
이 예제들은 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
| 문자열 | 예 | 변경 로그를 생성할 버전입니다. 형식은 의미 있는 버전을 따라야 합니다. |
config_file
| 문자열 | 아니오 | 프로젝트의 Git 리포지토리 내의 변경 로그 구성 파일 경로입니다. 기본값은 .gitlab/changelog_config.yml 입니다.
|
date
| 날짜 및 시간 | 아니오 | 릴리스의 날짜와 시간입니다. ISO 8601 형식을 사용합니다. 예: 2016-03-11T03:45:40Z . 기본값은 현재 시간입니다.
|
from
| 문자열 | 아니오 | 변경 로그 생성에 사용할 커밋 범위의 시작지점(SHA)입니다. 이 커밋 자체는 목록에 포함되지 않습니다. |
to
| 문자열 | 아니오 | 변경 로그 생성에 사용할 커밋 범위의 끝지점(SHA)입니다. 이 커밋은 목록에 포함됩니다. 기본값은 기본 프로젝트 브랜치의 HEAD입니다. |
trailer
| 문자열 | 아니오 | 커밋을 포함하는 데 사용할 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"
}