徽章
徽章是一种统一的方式,来呈现有关您的项目的浓缩信息。 徽章由一个小图片和图片指向的 URL 组成。 在极狐GitLab 中,徽章显示在项目描述下方。 您可以在项目和群组级别使用徽章。
可用的徽章
极狐GitLab 提供以下流水线徽章:
极狐GitLab 还支持自定义徽章。
流水线状态徽章
流水线状态徽章表示项目中最新流水线的状态。 根据流水线的状态,徽章可以具有以下值之一:
pending
running
passed
failed
skipped
manual
canceled
unknown
您可以使用以下链接访问流水线状态徽章图片:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg
仅显示非跳过状态
要使流水线状态标志仅显示最后一个未跳过的状态,请使用 ?ignore_skipped=true
查询参数:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true
测试覆盖率报告徽章
测试覆盖率报告徽章表示项目中测试的代码百分比。 该值是根据最新成功的流水线计算得出的。
您可以使用以下链接访问测试覆盖率报告徽章图片:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg
您可以为每个作业日志匹配的覆盖率报告定义正则表达式。 这意味着流水线中的每个作业都可以定义测试覆盖百分比值。
要从特定作业获取覆盖率报告,请将 job=coverage_job_name
参数添加到 URL。
例如,您可以使用类似于以下的代码将 coverage
作业的测试覆盖率报告徽章添加到 Markdown 文件中:
![coverage](https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?job=coverage)
测试覆盖率报告徽章颜色和限制
徽章的默认颜色和限制如下:
- 95 - 100% - 好 (
#4c1
) - 90 - 95% - 可接受 (
#a3c51c
) - 75 - 90% - 中等 (
#dfb317
) - 0 - 75% - 低 (
#e05d44
) - 无覆盖率 - 未知 (
#9f9f9f
)
您可以使用以下附加参数覆盖限制(引入于 14.4 版本):
-
min_good
(默认 95,可以使用 3 到 100 之间的任何值) -
min_acceptable
(默认 90,可以使用 2 和 min_good-1 之间的任何值) -
min_medium
(默认 75,可以使用 1 到 min_acceptable-1 之间的任何值)
如果设置了无效边界,极狐GitLab 会自动将其调整为有效边界。例如,min_good
设置为 80
,并且 min_acceptable
设置为 85
(太高),极狐GitLab 会自动将 min_acceptable
设置为 79
(min_good
- 1
)。
最新发布徽章
引入于 14.8 版本。
最新发布徽章表示您的项目的最新发布标签名称。 如果没有发布,则显示“无”。
您可以使用以下链接访问最新发布徽章的图片:
https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg
默认情况下,徽章获取使用 released_at
时间和 ?order_by
查询参数排序的版本。
https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at
您可以使用 value_width
参数更改版本名称字段的宽度(引入于 15.10 版本)。
该值必须在 1 到 200 之间,默认值为 54。
如果您设置的值超出范围,极狐GitLab 会自动将其调整为默认值。
项目徽章
徽章可以由维护者或所有者添加到项目中,并且在项目的概览页面上可见。 如果您发现必须为多个项目添加相同的徽章,您可能需要在群组级别添加它们。
向项目添加徽章
为项目添加新徽章:
- 在顶部栏上,选择 主菜单 > 项目 并找到您的项目。
- 在左侧边栏中,选择 设置 > 通用。
- 展开 徽章。
- 在 链接 下,输入徽章应指向的 URL,在 徽章图片网址 下,输入应显示的图片的 URL。
- 选择 添加徽章。
为项目添加徽章后,您可以在表单下方的列表中看到徽章。
编辑或删除项目徽章
要编辑徽章,请选择 编辑 ()。
要删除徽章,请选择 删除 ()。
示例项目徽章:流水线状态
一个常见的项目徽章表示极狐GitLab CI 流水线状态。
将此徽章添加到项目中:
- 在顶部栏上,选择 主菜单 > 项目 并找到您的项目。
- 在左侧边栏中,选择 设置 > 通用。
- 展开 徽章。
- 在 名称 下,输入 流水线状态。
- 在 链接 下,输入以下 URL:
https://jihulab.com/%{project_path}/-/commits/%{default_branch}
- 在 徽章图片网址 下,输入以下 URL:
https://jihulab.com/%{project_path}/badges/%{default_branch}/pipeline.svg
- 选择 添加徽章。
群组徽章
通过向群组添加徽章,您可以为群组中的所有项目添加并强制实施项目级徽章。群组徽章在属于该组的任何项目的概览页面上可见。
如果您需要为每个项目提供单独的徽章,则可以:
- 在项目级别添加徽章。
- 使用 placeholders。
向群组添加徽章
要将新徽章添加到群组:
- 在顶部栏上,选择 主菜单 > 群组 并找到您的群组。
- 在左侧边栏中,选择 设置 > 通用。
- 展开 徽章。
- 在“链接”下,输入徽章应指向的 URL,在“徽章图片网址”下输入应显示的图片的 URL。
- 选择 添加徽章。
将徽章添加到群组后,您可以在表单下方的列表中看到它。
编辑或删除群组徽章
要编辑徽章,请选择 编辑 ()。
要删除徽章,请选择 删除 ()。
只能在群组级别编辑或删除与群组关联的徽章。
查看流水线徽章的 URL
您可以查看徽章的链接。 然后您可以使用该链接,将徽章嵌入到您的 HTML 或 Markdown 页面中。
- 在顶部栏中,选择 主菜单 > 项目 并找到您的项目。
- 在左侧边栏中,选择 设置 > CI/CD。
- 展开 流水线通用设置。
- 在 流水线状态、覆盖率报告 或 最新发布 部分,查看图片的 URL。
自定义徽章
您可以自定义徽章的以下方面:
- 样式
- 文本
- 宽度
- 图片
自定义徽章样式
通过将 style=style_name
参数添加到 URL,可以以不同的样式呈现流水线徽章。有两种款式可供选择:
-
Flat(默认值):
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat
-
Flat square:
https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square
自定义徽章文本
用户可以自定义徽章的文本,区分在同一流水线中运行的多个覆盖率作业。
通过将 key_text=custom_text
和 key_width=custom_key_width
参数添加到 URL,来自定义徽章文本和宽度:
https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130
自定义徽章图片
如果您想使用默认徽章以外的徽章,请在项目或群组中使用自定义徽章图片。
先决条件:
- 直接指向所需徽章图片的有效 URL。如果图片位于极狐GitLab 仓库中,请使用图片的原始链接。
使用 placeholders,以下是一个示例徽章图片 URL,它引用仓库根目录中的原始图片:
https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg
要将新徽章添加到具有自定义图片的群组或项目:
- 在顶部栏上,选择 主菜单 并找到您的群组或项目。
- 在左侧边栏中,选择 设置 > 通用。
- 展开 徽章。
- 在 名称 下,输入徽章的名称。
- 在 链接 下,输入徽章应指向的 URL。
- 在 徽章图片网址 下,输入直接指向应显示的自定义图片的 URL。
- 选择 添加徽章。
要了解如何使用通过流水线生成的自定义图片,请参阅关于通过 URL 访问最新作业产物的文档。
Placeholders
徽章指向的 URL 和图片 URL 都可以包含 placeholders。可以使用以下 placeholders:
-
%{project_path}
:项目的路径,包括父组 -
%{project_title}
:项目标题 -
%{project_name}
:项目名称 -
%{project_id}
:与项目关联的数据库 ID -
%{default_branch}
:为项目仓库配置的默认分支名称 -
%{commit_sha}
:最近提交到项目仓库默认分支的 ID