仓库 API

列出仓库树

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

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

caution此端点正在更改为基于键集的分页。迭代带有数字 (?page=2) 的结果页面已经废弃。 极狐GitLab 15.0 支持使用数字进行迭代。使用新的键集分页系统
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。选项是 tar.gztar.bz2tbztbz2tb2bz2tarzip。例如,指定 archive.zip 将发送 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 用于直接比较 fromto (from..to),false 使用合并基进行比较 (fromto)’。默认为 false
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"
}

贡献者

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

GET /projects/:id/repository/contributors
caution截至 13.4,additionsdeletions 属性已经废弃,因为他们经常返回 0

支持的属性:

参数 类型 是否必需 描述
id integer or string yes 授权用户拥有的 ID 或 URL 编码的项目路径
order_by string no 返回按照 nameemailcommits(按提交日期排序)字段进行排序的贡献者。默认为 commits
sort string no 返回按照 ascdesc 顺序排序的贡献者。默认为 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[]=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 为所有使用特定的 Git Trailer 的提交生成更新日志。

此过程的输出是给定项目的 Git 仓库中的更新日志文件中的一个新部分。输出格式为 Markdown,可以定制。

POST /projects/:id/repository/changelog

支持的属性:

参数 类型 是否必需 描述
version string yes 为其生成更新日志的版本。格式必需遵循语义版本控制
from string no 用于生成更新日志的提交(作为 SHA)范围的开始。此提交本身不包含在列表中
to string no 用于更新日志的提交(作为 SHA)范围的结束。此提交包含在列表中。默认为 branch 属性中指定的分支
date datetime no 发布的日期和时间,默认为当前时间
branch string no 提交更新日志更改的分支,默认为项目的默认分支
trailer string no 用于包含提交的 Git Trailer,默认为 Changelog
config_file string no 项目 Git 仓库中更新日志配置文件的路径。默认为 .gitlab/changelog_config.yml
file string no 更改提交到的文件,默认为 CHANGELOG.md
message string no 提交更改时生成的提交信息,默认为 Add changelog for version X,其中 X 是 version 参数的值
caution极狐GitLab Trailer 区分大小写。如果您将 trailer 字段设置为 Example,极狐GitLab 不会包括使用 exampleeXaMpLE 或其他不完全Example Trailer 的提交。
cautionfromto,最多允许 15000 个提交。要禁用这个限制,请关闭功能标记 changelog_commits_limitation

如果未指定 from 属性,极狐GitLab 使用 version 属性中指定的版本之前的最后一个稳定版本的 Git 标签。 这要求 Git 标签名称遵循特定格式,允许极狐GitLab 从标签名称中提取版本。默认情况下,极狐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.11.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,开发人员使用以下值:featurebugperformance

您可以使用以下 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 %} 标记进行终止。 ifeach 语句都需要单个参数。

例如,如果我们有变量 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 表示 barfoo 的子字段):

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

如果无法确定数据,authormerge_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

支持的参数:

参数 类型 是否必需 描述
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"
}