• 列出仓库树
• 从仓库获取 Blob
• 原始 Blob 内容
• 获取文件归档
• 比较分支、标签或提交
• 贡献者
• 合并基
• 向更新日志文件添加更新日志数据
  • from 参数要求
  • 示例
  • 如何工作
  • 还原的提交
  • 自定义更新日志输出
  • 自定义模板
  • 模板数据
  • 提取版本时，自定义标签格式
• 生成更新日志数据

仓库 API

列出仓库树

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

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

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

GET /projects/:id/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"
  }
]

从仓库获取 Blob

允许您接收仓库中 Blob 的信息，例如大小和内容。 Blob 内容采用 Base64 编码。如果仓库可公开访问，则无需身份验证就可以访问此端点。

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

支持的参数：

原始 Blob 内容

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

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

支持的参数：

获取文件归档

• 对包括 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

支持的参数：

请求示例：

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

支持的参数：

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

贡献者

• 参数 additions 和 deletions 废弃于极狐GitLab 13.4，因为它们一直返回 0。
• 参数 additions 和 deletions 移除于极狐GitLab 14.0。

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

GET /projects/:id/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
}]

合并基

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

GET /projects/:id/repository/merge_base

请求示例：

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

响应示例：

{
  "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 13.9。
• 提交范围限制引入于极狐GitLab 15.1，功能标记为 changelog_commits_limitation。默认启用。

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

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

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

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

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

示例

这些示例使用 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"

如何工作

更新日志是根据提交标题生成的。仅在其包含特定的 Git Trailer 时才包含提交。 极狐GitLab 使用此 Trailer 的值对变更进行分类。

极狐GitLab 使用 Git Trailer，因为 Git Trailer 由开箱即用的 Git 支持。 我们使用提交作为输入，因为这是每个项目都使用的唯一数据源。此外，当在镜像上进行操作时，可以检索提交。 这对极狐GitLab 本身很重要，因为在安全发布期间，我们可能需要包含来自公共项目和私有安全镜像的更改。

您可以使用模板自定义更新日志的格式。

可以在编辑提交消息时手动添加 Trailer。要使用 Changelog 的默认 Trailer 将提交包括进来并将其归类为功能，可以像这样将 Trailer 添加到提交消息中：

<Commit message subject>

<Commit message description>

Changelog: feature

还原的提交

引入于极狐GitLab 13.10。

为范围生成更新日志时，极狐GitLab 会忽略范围内添加的和还原的提交。 如果他们使用用于生成更新日志的 Git Trailer，会包括还原提交自身。

想象以下场景：您有三个提交：A、B 和 C。要生成更新日志，您使用默认 Trailer Changelog。 A 和 B 都使用这个 Trailer。 提交 C 是还原提交 B 的提交。为这个范围生成更新日志时，极狐GitLab 仅包含提交 A。

通过查找消息中包含 This reverts commit SHA 模式的提交来检测还原提交，其中 SHA 是被还原的提交的 SHA。

如果还原提交包含用于生成更新日志（上例中的Changelog）的 Trailer，还原提交本身包括在内。

自定义更新日志输出

使用存储在您项目的 Git 仓库中的 YAML 配置文件自定义输出。默认的配置文件路径是 .gitlab/changelog_config.yml。

您可以在此文件中设置以下变量：

• date_format：在新添加的更新日志数据的标题中使用的日期格式。使用常规的 strftime 格式。
• template：用于生成更新日志数据的自定义模板。
• categories：将原始类别名称映射到更新日志中要使用的名称的哈希。
• include_groups：包含用户的群组完整路径列表，无论项目成员身份如何，这些用户的贡献都应计入。生成更新日志的用户必须有权访问每个群组，否则成员将不会被记入。

使用默认设置，生成更新日志会生成与以下行在一起的一部分内容：

## 1.0.0 (2021-01-05)

### Features (4 changes)

- [Feature 1](gitlab-org/gitlab@123abc) by @alice ([merge request](gitlab-org/gitlab!123))
- [Feature 2](gitlab-org/gitlab@456abc) ([merge request](gitlab-org/gitlab!456))
- [Feature 3](gitlab-org/gitlab@234abc) by @steve
- [Feature 4](gitlab-org/gitlab@456)

每个部分都以包含版本和发布日期的标题开头。 虽然日期的格式可以自定义，但标题的其余部分不能改变。添加新部分时，极狐GitLab 会解析这些标题以确定新部分在文件中应该放置的位置。极狐GitLab 根据其版本，而不是日期对部分进行排序。

每个部分都可以有类别，每个类别都有相应的变更。在上面的示例中，“功能”就是这样一个类别。 您可以自定义这些部分的格式。

部分名称源自用于包含或不包含提交的 Git Trailer 的值。

例如，如果要使用的 Trailer 名为 Changelog，并且它的值是 feature，那么提交会被分在 feature 类别中。 这些原始值的名称可能与您想在更新日志中显示的不同，您可以重新映射。假设我们使用 Changelog Trailer，开发人员使用以下值：feature、bug 和 performance。

您可以使用以下 YAML 配置文件重新映射：

---
categories:
  feature: Features
  bug: Bug fixes
  performance: Performance improvements

生成更新日志数据时，类别标题为 ### Features、### Bug fixes 和 ### Performance improvements。

自定义模板

使用模板生成类别部分。默认模板为：

{% if categories %}
{% each categories %}
### {{ title }} ({% if single_change %}1 change{% else %}{{ count }} changes{% end %})

{% each entries %}
- [{{ title }}]({{ commit.reference }})\
{% if author.credit %} by {{ author.reference }}{% end %}\
{% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %}

{% end %}

{% end %}
{% else %}
No changes.
{% end %}

{% ... %} 标签用于语句，{{ ... }} 用于打印数据。语句必须使用 {% end %} 标记进行终止。if 和 each 语句都需要单个参数。

例如，如果我们有变量 valid，当此值为真时，我们想显示”是”，否则显示”否”。我们可以这样做：

{% if valid %}
yes
{% else %}
nope
{% end %}

else 的使用是可选的。当一个值非空或是布尔值 true 时，它被认为是真的。 空数组和哈希被认为是假的。

使用 each 完成循环，并且循环内的变量被限定在它的范围内。 使用变量标签 {{ it }}在循环中引用当前值。其他变量从当前循环值中读取它们的值。例如这个模板：

{% each users %}
{{name}}
{% end %}

假设 users 是一个对象数组，每个对象都有 name 字段，然后打印每个用户的名称。

使用变量标签，您可以访问嵌套对象。例如，{{ users.0.name }} 打印 users 变量中第一个用户的名称。

如果一行以反斜杠结尾，则忽略下一个换行符。这使您可以跨多行包装代码，而无需在 Markdown 输出中引入不必要的换行符。

通过 {% 和 %} 的标签（称为表达式标签）使用紧挨着它们的换行符（如果有的话）。也就是说：

---
{% if foo %}
bar
{% end %}
---

编译成以下内容：

---
bar
---

而不是：

---

bar

---

您可以像这样在您的配置中指定自定义模板：

---
template: |
  {% if categories %}
  {% each categories %}
  ### {{ title }}

  {% each entries %}
  - [{{ title }}]({{ commit.reference }})\
  {% if author.credit %} by {{ author.reference }}{% end %}

  {% end %}

  {% end %}
  {% else %}
  No changes.
  {% end %}

指定模板时，您应该使用 template: | 而不是 template: >，因为后者不会在模板中保留换行符。

模板数据

在顶层，可以使用以下变量：

• categories：一个对象数组，每个更新日志类别一个。

在一个类别中，可以使用以下变量：

• title：类别的标题（重新映射后）。
• count：此类别中的条目数。
• single_change：一个布尔值，指示只有一个更改（true）还是多次更改（false）。
• entries：属于此类别的条目。

在一个条目中，可以使用以下变量（这里 foo.bar 表示 bar 是 foo 的子字段）：

• author.contributor：当作者不是项目成员时，布尔值设置为 true，否则为 false。
• author.credit：当 author.contributor 为 true 或配置了 include_groups，并且作者是群组的成员时，布尔被设置为 true。
• author.reference：对提交作者的引用（@alice）。
• commit.reference：对提交的引用，例如： gitlab-org/gitlab@0a4cdd86ab31748ba6dac0f69a8653f206e5cfc7。
• commit.trailers：包含所有提交主体中的 Git trailer 的对象。
• merge_request.reference：初次引入更改（例如，gitlab-org/gitlab!50063）的合并请求的引用。
• title：更新日志条目的标题（提交标题）。

如果无法确定数据，author 和 merge_request 对象可能不存在。 例如，当创建没有对应的合并请求的提交时，不显示合并请求。

提取版本时，自定义标签格式

引入于极狐GitLab 13.11。

极狐GitLab 使用正则表达式（使用 re2 引擎和语法）提取来自标签名称的语义版本。 默认的正则表达式是：

^v?(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<pre>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<meta>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

这个正则表达式是基于官方的语义版本控制 正则表达式，还包括对以字母 v 开头的标签名称的支持。

如果您的项目使用其他标签格式，您可以指定其他正则表达式。使用的正则表达式必须生成以下捕获群组。如果缺少这些捕获群组中的任何一个，则忽略该标签：

• major
• minor
• patch

以下捕获群组可选：

• pre：如果设置，标签将被忽略。忽略 pre 标签确定生成更新日志的提交的范围时，不考虑发布候选标签和其他预发布标签。
• meta：可选。指定构建元数据。

使用这些信息，极狐GitLab 构建了一个 Git 标签及其发布版本的图。 然后它根据从每个标签中提取的版本确定最新标签。

要指定自定义正则表达式，请在您的更新日志配置 YAML 文件中使用 tag_regex。例如，此模式匹配标签名称，例如 version-1.2.3 但不是 version-1.2。

---
tag_regex: '^version-(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$'

您可以使用网站，例如 regex101 来测试您的正则表达式是否有效。如果正则表达式语法无效，生成更新日志时会产生错误。

生成更新日志数据

引入于极狐GitLab 14.6。

根据仓库中的提交生成更新日志数据，无需将它们提交到更新日志文件中。

与 POST /projects/:id/repository/changelog 的工作方式完全一样，除了更新日志数据不专属于任何更新日志文件。

GET /projects/:id/repository/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"
}