{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

列出存储库树

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

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

{{< alert type=”warning” >}}

此端点在极狐GitLab 15.0 中更改为 基于密钥集的分页。不支持使用数字 (?page=2) 进行结果的页面迭代。

{{< /alert >}}

{{< alert type=”warning” >}}

在版本 17.7 中，更新了请求路径未找到时的错误处理行为。端点现在返回状态码 404 Not Found。之前，状态码为 200 OK。

如果您的实现依赖于接收 200 状态码和空数组来表示缺失路径，则必须更新您的错误处理以处理新的 404 响应。

{{< /alert >}}

GET /projects/:id/repository/tree

支持的属性：

属性 类型 必需 描述
id integer 或 string 是 项目的 ID 或 URL 编码路径。
page_token string 否 要获取下一页的树记录 ID。仅与密钥集分页一起使用。
pagination string 否 如果为 keyset，则使用 基于密钥集的分页方法。
path string 否 存储库中的路径。用于获取子目录的内容。
per_page integer 否 每页显示的结果数量。如果未指定，默认为 20。有关更多信息，请参阅 分页。
recursive boolean 否 用于获取递归树的布尔值。默认为 false。
ref string 否 存储库分支或标签的名称，如果未提供，则为默认分支。 
[
  {
    "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 integer 或 string 是 项目的 ID 或 URL 编码路径。
sha string 是 blob 的 SHA。

原始 blob 内容

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

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

支持的属性：

属性 类型 必需 描述
id integer 或 string 是 项目的 ID 或 URL 编码路径。
sha string 是 blob 的 SHA。

获取文件存档

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

对于 JihuLab.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 integer 或 string 是 项目的 ID 或 URL 编码路径。
path string 否 要下载的存储库子路径。如果为空字符串，默认为整个存储库。
sha string 否 要下载的提交 SHA。可以使用标签、分支引用或 SHA。如果未指定，默认为默认分支的尖端。
include_lfs_blobs boolean 否 确定是否在存档中包含 LFS 对象。默认为 true。设置为 false 时，LFS 对象被排除。
exclude_paths array 否 要从存档中排除的路径列表。

示例请求：

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

比较分支、标签或提交

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

GET /projects/:id/repository/compare

支持的属性：

属性 类型 必需 描述
id integer 或 string 是 项目的 ID 或 URL 编码路径。
from string 是 提交 SHA 或分支名称。
to string 是 提交 SHA 或分支名称。
from_project_id integer 否 要比较的项目 ID。
straight boolean 否 比较方法：true 表示在 from 和 to 之间直接比较 (from..to)，false 表示使用合并基比较 (from…to)。默认为 false。
unidiff boolean 否 以统一 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"
}

贡献者

{{< history >}}

  • ref 引入于极狐GitLab 17.4。

{{< /history >}}

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

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

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、分支名称或标签。

GET /projects/:id/repository/merge_base
属性 类型 必需 描述
id integer 或 string 是 项目的 ID 或 URL 编码路径。
refs array 是 要查找共同祖先的引用。接受多个引用。

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

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

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

{{< history >}}

  • 提交范围限制在极狐GitLab 15.1 中引入，使用名为 changelog_commits_limitation 的功能标志。默认禁用。
  • 在极狐GitLab 15.3 中在 JihuLab.com 上启用并在极狐GitLab 私有化部署中默认启用。
  • 在极狐GitLab 17.3 中 GA。功能标志 changelog_commits_limitation 被移除。

{{< /history >}}

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

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

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

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

POST /projects/:id/repository/changelog

支持的属性

变更日志支持这些属性：

属性 类型 必需 描述
version string 是 要为其生成变更日志的版本。格式必须遵循 语义版本控制。
branch string 否 要提交变更日志更改的分支。默认为项目的默认分支。
config_file string 否 项目 Git 存储库中变更日志配置文件的路径。默认为 .gitlab/changelog_config.yml。
date datetime 否 发布的日期和时间。默认为当前时间。
file string 否 要提交更改的文件。默认为 CHANGELOG.md。
from string 否 标记要包含在变更日志中的提交范围开始的提交的 SHA。此提交未包含在变更日志中。
message string 否 提交更改时使用的提交消息。默认为 Add changelog for version X，其中 X 是 version 参数的值。
to string 否 标记要包含在变更日志中的提交范围结束的提交的 SHA。此提交被包含在变更日志中。默认为 branch 属性中指定的分支。限制为 15000 次提交。
trailer string 否 用于包含提交的 Git trailer。默认为 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 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：

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 分支生成数据：

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 参数：

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 参数：

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 属性：

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"

生成变更日志数据

{{< history >}}

{{< /history >}}

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

工作原理与 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 trailer。默认为 Changelog。 
curl --header "PRIVATE-TOKEN: token" \
  --url "https://jihulab.com/gitlab-cn/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"
}

健康

{{< history >}}

  • 在极狐GitLab 17.10 中引入。使用名为 project_repositories_health 的功能标志。

{{< /history >}}

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

GET /projects/:id/repository/health

支持的属性：

属性 类型 必需 描述
generate boolean 否 是否应生成新的健康报告。如果端点返回 404，请设置此选项。

示例请求：

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

示例响应：

{
  "size": 42002816,
  "references": {
    "loose_count": 3,
    "packed_size": 315703,
    "reference_backend": "REFERENCE_BACKEND_FILES"
  },
  "objects": {
    "size": 39651458,
    "recent_size": 39461265,
    "stale_size": 190193,
    "keep_size": 0
  },
  "updated_at": "2025-02-26T03:42:13.015Z"
}

相关主题