이 API를 사용하여 Git 저장소를 관리합니다.

프로젝트의 모든 저장소 트리 목록 조회#

지정된 프로젝트의 모든 저장소 파일 및 디렉토리를 반환합니다. 저장소가 공개적으로 접근 가능한 경우 인증 없이 이 엔드포인트에 접근할 수 있습니다.

이 명령은 본질적으로 git ls-tree 명령과 동일한 기능을 제공합니다. 자세한 내용은 Git 내부 문서의 트리 오브젝트를 참조하세요.

GET /projects/:id/repository/tree

지원되는 속성:

성공 시 200 OK 및 트리 오브젝트 배열을 반환합니다.

요청 예시:

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

응답 예시:

[
  {
    "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로 인코딩됩니다. 저장소가 공개적으로 접근 가능한 경우 인증 없이 이 엔드포인트에 접근할 수 있습니다.

10 MB를 초과하는 블롭의 경우, 이 엔드포인트는 분당 5개 요청의 속도 제한이 있습니다.

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

지원되는 속성:

성공 시 200 OK 및 다음 응답 속성을 반환합니다:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/blobs/79f7bbd25901e8334750839545a9bd021f0e4c83"

응답 예시:

{
  "size": 1476,
  "encoding": "base64",
  "content": "VGhpcyBpcyBhIGJpbmFyeSBmaWxl",
  "sha": "79f7bbd25901e8334750839545a9bd021f0e4c83"
}

원시 블롭 내용 조회#

블롭 SHA로 블롭의 원시 파일 내용을 반환합니다. 저장소가 공개적으로 접근 가능한 경우 인증 없이 이 엔드포인트에 접근할 수 있습니다.

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

지원되는 속성:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/blobs/79f7bbd25901e8334750839545a9bd021f0e4c83/raw"

저장소에서 파일 아카이브 조회#

지정된 저장소의 파일 아카이브를 반환합니다. 저장소가 공개적으로 접근 가능한 경우 인증 없이 이 엔드포인트에 접근할 수 있습니다.

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

지원되는 속성:

요청 예시:

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

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

히스토리

• collapsed 및 too_large 응답 속성이 GitLab 18.4에서 도입되었습니다.

지정된 프로젝트에서 두 브랜치, 태그 또는 커밋 간의 차이점을 반환합니다. 저장소가 공개적으로 접근 가능한 경우 인증 없이 이 엔드포인트에 접근할 수 있습니다.

compare_timeout이 true인 경우, 비교가 크기 제한을 초과했거나 시간이 초과되었습니다:

• commits 배열은 항상 완전합니다.
• diffs 배열이 불완전할 수 있습니다.
• 개별 diff 오브젝트는 내용이 제한을 초과한 경우 빈 diff 문자열을 가질 수 있습니다.

GET /projects/:id/repository/compare

지원되는 속성:

성공 시 200 OK 및 다음 응답 속성을 반환합니다:

요청 예시:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/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+}",
    "collapsed": false,
    "too_large": false,
    "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"
}

기여자 목록 조회#

히스토리

• ref가 GitLab 17.4에서 도입되었습니다.

저장소 기여자 목록을 가져옵니다. 저장소가 공개적으로 접근 가능한 경우 인증 없이 이 엔드포인트에 접근할 수 있습니다.

반환된 커밋 수에는 머지 커밋이 포함되지 않습니다.

GET /projects/:id/repository/contributors

지원되는 속성:

성공 시 200 OK 및 다음 응답 속성을 반환합니다:

요청 예시:

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개 이상의 참조에 대한 공통 조상을 가져옵니다.

GET /projects/:id/repository/merge_base

지원되는 속성:

성공 시 200 OK 및 다음 응답 속성을 반환합니다:

요청 예시 (가독성을 위해 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": "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",
  "trailers": {},
  "extended_trailers": {},
  "web_url": "https://gitlab.example.com/example-group/example-project/-/commit/1a0b36b3cdad1d2ee32457c102a8c0b7056fa863"
}

체인지로그 데이터 생성#

히스토리

• GitLab 17.7에서 CI/CD 잡 토큰을 통한 인증이 도입되었습니다.
• config_file_ref 속성이 GitLab 18.2에서 도입되었습니다.

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

POST /projects/:id/repository/changelog와 정확히 동일하게 동작하지만, 체인지로그 데이터가 체인지로그 파일에 커밋되지 않습니다.

GET /projects/:id/repository/changelog

지원되는 속성:

성공 시 200 OK 및 다음 응답 속성을 반환합니다:

요청 예시:

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

파일에 체인지로그 데이터 추가#

히스토리

• GitLab 17.3에서 일반적으로 사용 가능합니다. changelog_commits_limitation 기능 플래그가 제거되었습니다.
• config_file_ref가 GitLab 18.2에서 도입되었습니다.

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

시맨틱 버전과 커밋 범위가 주어지면, GitLab은 특정 Git 트레일러를 사용하는 모든 커밋에 대한 체인지로그를 생성합니다. GitLab은 프로젝트의 Git 저장소에 있는 체인지로그 파일에 새로운 Markdown 형식의 섹션을 추가합니다. 출력 형식은 사용자 지정할 수 있습니다.

성능 및 보안상의 이유로, 체인지로그 구성 파싱은 2초로 제한됩니다. 이 제한은 잘못된 체인지로그 템플릿으로 인한 잠재적 DoS 공격을 방지하는 데 도움이 됩니다. 요청이 시간 초과되면, changelog_config.yml 파일 크기를 줄이는 것을 고려하세요.

사용자 문서는 체인지로그를 참조하세요.

POST /projects/:id/repository/changelog

체인지로그는 다음 속성을 지원합니다:

각주:

1. version 속성은 v 접두사를 포함하거나 생략할 수 있습니다. 1.0.0과 v1.0.0 모두 동일한 결과를 생성합니다. GitLab 17.0에서 도입되었습니다.

2. from이 지정되지 않으면, GitLab은 지정된 버전 이전의 마지막 안정적인 버전 태그를 자동으로 찾습니다. GitLab은 시맨틱 버저닝을 따르는 X.Y.Z 또는 vX.Y.Z 형식의 태그를 인식합니다.

   예를 들어, version이 2.1.0이면 GitLab은 태그 v2.0.0을 사용합니다. version이 1.1.1 또는 1.2.0이면 GitLab은 태그 v1.1.0을 사용합니다. v1.0.0-pre1과 같은 사전 릴리스 태그는 무시됩니다.

   적합한 태그를 찾을 수 없으면, API가 오류를 반환하고 from 속성을 명시적으로 지정해야 합니다.

예시#

이 예시는 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" \
  --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"

브랜치를 파라미터로 지정하려면 to 속성을 사용합니다:

curl --request GET \
  --header "PRIVATE-TOKEN: token" \
  --url "https://gitlab.com/api/v4/projects/42/repository/changelog?version=1.0.0&to=release/x.x.x"

수동 체인지로그 파일에서 마이그레이션#

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

이슈 444183은 체인지로그 파일에서 버전 헤더 형식을 사용자 지정하는 것을 제안합니다. 하지만 해당 이슈가 완료될 때까지 체인지로그 파일에서 예상되는 버전 헤더 형식은 X.Y.Z입니다.

헬스#

히스토리

• GitLab 17.10에서 project_repositories_health 기능 플래그 뒤에 보호되어 도입되었습니다.
• GitLab 18.1에서 새 필드가 추가되었습니다.

프로젝트 저장소의 헬스와 관련된 통계를 가져옵니다.

generate가 true인 경우 이 엔드포인트는 프로젝트당 시간당 5개 요청으로 속도 제한됩니다. 이 엔드포인트는 저장소에 푸시 접근 권한이 있는 사용자에게만 제공됩니다.

GET /projects/:id/repository/health

지원되는 속성:

성공 시 200 OK 및 저장소 헬스 통계를 반환합니다.

요청 예시:

curl --header "PRIVATE-TOKEN: token" \
  --url "https://gitlab.com/api/v4/projects/42/repository/health"

응답 예시:

{
  "size": 2619748827,
  "references": {
    "loose_count": 13,
    "packed_size": 333978,
    "reference_backend": "REFERENCE_BACKEND_FILES"
  },
  "objects": {
    "size": 2180475409,
    "recent_size": 2180453999,
    "stale_size": 21410,
    "keep_size": 0,
    "packfile_count": 1,
    "reverse_index_count": 1,
    "cruft_count": 0,
    "keep_count": 0,
    "loose_objects_count": 36,
    "stale_loose_objects_count": 36,
    "loose_objects_garbage_count": 0
  },
  "commit_graph": {
    "commit_graph_chain_length": 1,
    "has_bloom_filters": true,
    "has_generation_data": true,
    "has_generation_data_overflow": false
  },
  "bitmap": null,
  "multi_pack_index": {
    "packfile_count": 1,
    "version": 1
  },
  "multi_pack_index_bitmap": {
    "has_hash_cache": true,
    "has_lookup_table": true,
    "version": 1
  },
  "alternates": null,
  "is_object_pool": false,
  "last_full_repack": {
    "seconds": 1745892013,
    "nanos": 0
  },
  "updated_at": "2025-05-14T02:31:08.022Z"
}

응답의 각 필드에 대한 설명은 RepositoryInfoResponse protobuf 메시지를 참조하세요.

관련 항목#

• 체인지로그에 대한 사용자 문서