列出仓库树
从仓库获取 Blob
原始 Blob 内容
获取文件归档
比较分支、标签或提交
贡献者
合并基
向更新日志文件添加更新日志数据
生成更新日志数据
相关主题

仓库 API

列出仓库树

迭代带有数字 (?page=2) 的结果页面废弃于极狐GitLab 14.3。

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

此命令提供与 git ls-tree 命令基本相同的功能。详情请参见 Git 内部文档中的树对象。

此端点在 15.0 中变更为基于键集的分页，迭代带有数字 (?page=2) 的结果页面已废弃。

GET /projects/:id/repository/tree

支持的参数：

参数	类型	是否必需	描述
`id`	integer or string	yes	经过身份验证的用户拥有的项目 ID 或 URL 编码的路径
`path`	string	no	仓库内的路径。用于获取子目录的内容
`ref`	string	no	仓库分支名称或标签名称。如未给定，则为默认分支名称
`recursive`	boolean	no	用于获取递归树的布尔值（默认为 False）
`per_page`	integer	no	每页展示的结果数量。如未指定，默认为 `20`。了解更多分页的内容
`pagination`	string	no	如果设置为 `keyset`，则使用键集分页方法
`page_token`	string	no	获取下一页的树记录 ID。仅与键集分页一起使用

[
  {
    "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 or string	yes	经过身份验证的用户拥有的项目 ID 或 URL 编码的路径
`sha`	string	yes	Blob SHA

原始 Blob 内容

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

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

支持的参数：

参数	类型	是否必需	描述
`id`	integer or string	yes	经过身份验证的用户拥有的项目 ID 或 URL 编码的路径
`sha`	string	yes	Blob SHA

获取文件归档

对包括 Git LFS Blob 的支持引入于极狐GitLab 13.5。

对下载子文件夹的支持引入于极狐GitLab 14.4。

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

对于 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 or string	yes	经过身份验证的用户拥有的项目 ID 或 URL 编码的路径
`sha`	string	no	要下载的提交 SHA。可以使用标签、分支引用或 SHA。如果未指定，则默认为默认分支的尖端
`path`	string	no	要下载的仓库的子路径。如果字符串为空，则默认为整个仓库

请求示例：

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

比较分支、标签或提交

如果仓库可公开访问，则无需身份验证就可以访问此端点。

GET /projects/:id/repository/compare

支持的参数：

参数	类型	是否必需	描述
`id`	integer or string	yes	经过身份验证的用户拥有的项目 ID 或 URL 编码的路径
`from`	string	yes	提交 SHA 或分支名称
`to`	string	yes	提交 SHA 或分支名称
`from_project_id`	integer	no	进行比较的 ID
`straight`	boolean	no	比较方法，`true` 用于直接比较 `from` 和 `to` (`from`..`to`)，`false` 使用合并基进行比较 (`from`…`to`)’。默认为 `false`
`unidiff`	boolean	No	以统一差异格式展现差异。默认为 false。引入于极狐GitLab 16.5。

GET /projects/:id/repository/compare?from=master&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": "--- a/files/js/application.js\n+++ b/files/js/application.js\n@@ -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/thedude/gitlab-foss/-/compare/ae73cb07c9eeaf35924a10f713b364d32b2dd34f...0b4bc9a49b562e85de7cc9e834518ea6828729b9"
}

贡献者

ref 引入于极狐GitLab 17.4。

获取仓库贡献者列表。如果仓库可公开访问，则无需进行身份验证就可以访问此端点。

返回的提交数量不包含合并请求提交。

GET /projects/:id/repository/contributors

支持的参数：

参数	类型	是否必需	描述
`id`	integer or string	yes	经过身份验证的用户拥有的项目 ID 或 URL 编码的路径
`ref`	string	no	仓库分支或标签的名称。如未给定，则为默认分支。
`order_by`	string	no	返回按照 `name`、`email` 或 `commits`（按提交日期排序）字段进行排序的贡献者。默认为 `commits`
`sort`	string	no	返回按照 `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
}]

合并基

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

GET /projects/:id/repository/merge_base

参数	类型	是否必需	描述
`id`	integer or string	yes	项目 ID 或 URL 编码的路径
`refs`	array	yes	找到共同祖先的 refs，接受多个 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": "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"
}

向更新日志文件添加更新日志数据

提交范围限制引入于极狐GitLab 15.1，使用名为 changelog_commits_limitation 的功能标志。默认情况下禁用。

在极狐GitLab 15.3 中为私有化部署和 SaaS 产品启用。

在极狐GitLab 17.3 中 GA。changelog_commits_limitation 功能标志被移除。

根据仓库中的提交生成更新日志数据。

给定一个语义版本和一系列提交，极狐GitLab 为所有使用特定的 Git Trailer 的提交生成更新日志。

极狐GitLab 向项目的 Git 仓库中的更新日志文件添加一个新的 Markdown 格式的内容，且输出格式可以定制。

POST /projects/:id/repository/changelog

支持的参数

更新日志支持以下参数：

参数	类型	是否必需	描述
`version`	string	yes	为其生成更新日志的版本。格式必需遵循语义版本控制
`from`	string	no	标记更新日志中提交范围开始的提交 SHA。此提交本身不包含在列表中
`to`	string	no	标记更新日志中提交范围结束的提交 SHA。此提交包含在更新日志中。默认为 `branch` 参数中指定的分支。最高为 15000 个提交，除非禁用 `changelog_commits_limitation` 功能标志
`date`	datetime	no	发布的日期和时间，默认为当前时间
`branch`	string	no	提交更新日志更改的分支，默认为项目的默认分支
`trailer`	string	no	用于包含提交的 Git Trailer，默认为 `Changelog`。区分大小写，`Example` 不匹配 `example` 或 `eXaMpLE`
`config_file`	string	no	项目 Git 仓库中更新日志配置文件的路径。默认为 `.gitlab/changelog_config.yml`
`file`	string	no	更改提交到的文件，默认为 `CHANGELOG.md`
`message`	string	no	提交更改时使用的提交信息，默认为 `Add changelog for version X`，其中 X 是 `version` 参数的值

`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，因为预发布标签被忽略。

如果未指定 from 且未找到要使用的标签，则 API 会产生错误。要解决此类错误，您必须明确指定 from 参数的值。

从手动管理的表更日志迁移到 Git trailers

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

示例

这些示例使用 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" "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，请使用 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`	string	yes	为其生成更新日志的版本。格式必需遵循语义版本控制
`from`	string	no	用于生成更新日志的提交（作为 SHA）范围的开始。此提交本身不包含在列表中
`to`	string	no	用于更新日志的提交（作为 SHA）范围的结束。此提交包含在列表中。默认为 `branch` 参数中指定的分支
`date`	datetime	no	发布的日期和时间，格式为 ISO 8601。例如：`2016-03-11T03:45:40Z`。默认为当前时间
`trailer`	string	no	用于包括提交的 Git Trailer，默认为 `Changelog`
`config_file`	string	no	项目 Git 仓库中的更新日志配置文件的路径。默认为 `.gitlab/changelog_config.yml`

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

列出仓库树

从仓库获取 Blob

原始 Blob 内容

获取文件归档

比较分支、标签或提交

贡献者

合并基

向更新日志文件添加更新日志数据

支持的参数

from 参数要求

从手动管理的表更日志迁移到 Git trailers

示例

生成更新日志数据

相关主题

`from` 参数要求