仓库 API

列出存储库树#

获取项目中存储库文件和目录的列表。如果存储库是公开访问的，则可以无需身份验证访问此端点。

此命令基本上提供与 git ls-tree 命令相同的功能。有关更多信息，请参阅 Git 内部文档中的 树对象 部分。

plaintext
GET /projects/:id/repository/tree

支持的属性：

json
1[
2  {
3    "id": "a1e8f8d745cc87e3a9248358d9352bb7f9a0aeba",
4    "name": "html",
5    "type": "tree",
6    "path": "files/html",
7    "mode": "040000"
8  },
9  {
10    "id": "4535904260b1082e14f867f7a24fd8c21495bde3",
11    "name": "images",
12    "type": "tree",
13    "path": "files/images",
14    "mode": "040000"
15  },
16  {
17    "id": "31405c5ddef582c5a9b7a85230413ff90e2fe720",
18    "name": "js",
19    "type": "tree",
20    "path": "files/js",
21    "mode": "040000"
22  },
23  {
24    "id": "cc71111cfad871212dc99572599a568bfe1e7e00",
25    "name": "lfs",
26    "type": "tree",
27    "path": "files/lfs",
28    "mode": "040000"
29  },
30  {
31    "id": "fd581c619bf59cfdfa9c8282377bb09c2f897520",
32    "name": "markdown",
33    "type": "tree",
34    "path": "files/markdown",
35    "mode": "040000"
36  },
37  {
38    "id": "23ea4d11a4bdd960ee5320c5cb65b5b3fdbc60db",
39    "name": "ruby",
40    "type": "tree",
41    "path": "files/ruby",
42    "mode": "040000"
43  },
44  {
45    "id": "7d70e02340bac451f281cecf0a980907974bd8be",
46    "name": "whitespace",
47    "type": "blob",
48    "path": "files/whitespace",
49    "mode": "100644"
50  }
51]

从存储库获取 blob#

允许您接收有关存储库中的 blob 的信息，例如大小和内容。Blob 内容经过 Base64 编码。如果存储库是公开访问的，则可以无需身份验证访问此端点。

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

支持的属性：

原始 blob 内容#

通过 blob SHA 获取 blob 的原始文件内容。如果存储库是公开访问的，则可以无需身份验证访问此端点。

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

支持的属性：

获取文件存档#

获取存储库的存档。如果存储库是公开访问的，则可以无需身份验证访问此端点。

对于 JihuLab.com 用户，此端点的速率限制阈值为每分钟 5 个请求。

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

format 是存档格式的可选后缀，默认为 tar.gz。例如，指定 archive.zip 以 ZIP 格式发送存档。可用选项有：

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

支持的属性：

示例请求：

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

比较分支、标签或提交#

如果存储库是公开访问的，则可以无需身份验证访问此端点。如果达到 差异限制，差异可以有一个空的差异字符串。

plaintext
GET /projects/:id/repository/compare

支持的属性：

plaintext
GET /projects/:id/repository/compare?from=main&to=feature

示例响应：

json
1{
2  "commit": {
3    "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
4    "short_id": "12d65c8dd2b",
5    "title": "JS fix",
6    "author_name": "Example User",
7    "author_email": "user@example.com",
8    "created_at": "2014-02-27T10:27:00+02:00"
9  },
10  "commits": [{
11    "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
12    "short_id": "12d65c8dd2b",
13    "title": "JS fix",
14    "author_name": "Example User",
15    "author_email": "user@example.com",
16    "created_at": "2014-02-27T10:27:00+02:00"
17  }],
18  "diffs": [{
19    "old_path": "files/js/application.js",
20    "new_path": "files/js/application.js",
21    "a_mode": null,
22    "b_mode": "100644",
23    "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+}",
24    "new_file": false,
25    "renamed_file": false,
26    "deleted_file": false
27  }],
28  "compare_timeout": false,
29  "compare_same_ref": false,
30  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/compare/ae73cb07c9eeaf35924a10f713b364d32b2dd34f...0b4bc9a49b562e85de7cc9e834518ea6828729b9"
31}

贡献者#

获取存储库贡献者列表。如果存储库是公开访问的，则可以无需身份验证访问此端点。

返回的提交计数不包括合并提交。

plaintext
GET /projects/:id/repository/contributors

支持的属性：

示例请求：

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

示例响应：

json
1[{
2  "name": "Example User",
3  "email": "example@example.com",
4  "commits": 117,
5  "additions": 0,
6  "deletions": 0
7}, {
8  "name": "Sample User",
9  "email": "sample@example.com",
10  "commits": 33,
11  "additions": 0,
12  "deletions": 0
13}]

合并基#

获取两个或多个引用的共同祖先，例如提交 SHA、分支名称或标签。

plaintext
GET /projects/:id/repository/merge_base

示例请求，引用已截断以便于阅读：

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

示例响应：

json
1{
2  "id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
3  "short_id": "1a0b36b3",
4  "title": "Initial commit",
5  "created_at": "2014-02-27T08:03:18.000Z",
6  "parent_ids": [],
7  "message": "Initial commit\n",
8  "author_name": "Example User",
9  "author_email": "user@example.com",
10  "authored_date": "2014-02-27T08:03:18.000Z",
11  "committer_name": "Example User",
12  "committer_email": "user@example.com",
13  "committed_date": "2014-02-27T08:03:18.000Z"
14}

将变更日志数据添加到变更日志文件#

基于存储库中的提交生成变更日志数据。

给定一个 语义版本 和一个提交范围，极狐GitLab 为使用特定 Git trailer 的所有提交生成变更日志。极狐GitLab 在项目的 Git 存储库中的变更日志文件中添加一个新的 Markdown 格式的部分。输出格式可以自定义。

出于性能和安全原因，解析变更日志配置的时间限制为 2 秒。此限制有助于防止来自格式错误的变更日志模板的潜在 DoS 攻击。如果请求超时，请考虑减小 changelog_config.yml 文件的大小。

有关用户文档，请参阅 变更日志。

plaintext
POST /projects/:id/repository/changelog

支持的属性#

变更日志支持这些属性：

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 trailer#

当您从现有的手动管理的变更日志文件迁移到使用 Git trailer 的文件时，请确保变更日志文件符合 预期格式。否则，通过 API 添加的新变更日志条目可能会插入到意外的位置。例如，如果手动管理的变更日志文件中的版本值指定为 vX.Y.Z 而不是 X.Y.Z，则使用 Git trailer 添加的新变更日志条目将追加到变更日志文件的末尾。

示例#

这些示例使用 cURL 执行 HTTP 请求。示例命令使用这些值：

• 项目 ID: 42
• 位置: 托管在 JihuLab.com
• 示例 API 令牌: token

此命令为版本 1.0.0 生成变更日志。

提交范围：

• 从上一个版本的标签开始。
• 结束于目标分支的最后一次提交。默认目标分支是项目的默认分支。

如果最后一个标签是 v0.9.0 且默认分支是 main，则此示例中包含的提交范围为 v0.9.0..main：

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

要在不同分支上生成数据，请指定 branch 参数。此命令从 foo 分支生成数据：

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

要使用不同的 trailer，请使用 trailer 参数：

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

要将结果存储在不同的文件中，请使用 file 参数：

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

要将分支作为参数指定，请使用 to 属性：

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

生成变更日志数据#

基于存储库中的提交生成变更日志数据，而不将其提交到变更日志文件中。

工作原理与 POST /projects/:id/repository/changelog 完全相同，只是变更日志数据不会提交到任何变更日志文件中。

plaintext
GET /projects/:id/repository/changelog

支持的属性：

shell
curl --header "PRIVATE-TOKEN: token" \
  --url "https://jihulab.com/gitlab-cn/api/v4/projects/42/repository/changelog?version=1.0.0"

示例响应，添加了换行符以便于阅读：

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

健康#

获取与项目存储库健康相关的统计信息。此端点的速率限制为每个项目每小时 5 个请求。

plaintext
GET /projects/:id/repository/health

支持的属性：

示例请求：

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

示例响应：

json
1{
2  "size": 42002816,
3  "references": {
4    "loose_count": 3,
5    "packed_size": 315703,
6    "reference_backend": "REFERENCE_BACKEND_FILES"
7  },
8  "objects": {
9    "size": 39651458,
10    "recent_size": 39461265,
11    "stale_size": 190193,
12    "keep_size": 0
13  },
14  "updated_at": "2025-02-26T03:42:13.015Z"
15}

相关主题#

• 变更日志 的用户文档
• 极狐GitLab 中 变更日志条目 的开发者文档