{{< details >}}

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

{{< /details >}}

极狐GitLab 徽章是呈现项目简要信息的一种统一方式。徽章由一个小图像和一个指向该图像的 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

你可以定义每个作业日志匹配的代码覆盖率的正则表达式。这意味着流水线中的每个作业都可以定义测试覆盖率百分比值。

要获取特定作业的覆盖率报告，请在 URL 中添加 job=coverage_job_name 参数。例如，你可以使用类似以下代码，将 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

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

Up to 意味着达到，但不包括上限。

{{< /alert >}}

更改默认限制

你可以通过在覆盖率报告徽章 URL 中传递以下查询参数来覆盖默认限制：

查询参数 可接受值 默认值
min_good 3 到 100 之间的任何值 95
min_acceptable 2 到 min_good−1 之间的任何值 90
min_medium 1 到 min_acceptable−1 之间的任何值 75

例如：

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?min_good=98&min_acceptable=75

如果你设置了无效边界，极狐GitLab 会自动调整为有效。例如，如果你将 min_good 设置为 80，将 min_acceptable 设置为 85，极狐GitLab 会将 min_acceptable 设置为 79（min_good - 1），因为最低可接受值不能高于最低良好值。

最新发布徽章

最新发布徽章指示项目的最新发布标签名称。如果没有发布，则显示 none。

你可以通过以下链接访问最新发布徽章图像：

https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg

默认情况下，徽章通过 ?order_by 查询参数按 released_at 时间排序获取发布。

https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at

你可以使用 value_width 参数更改发布名称字段的宽度（在极狐GitLab 15.10 中引入）。该值必须介于 1 和 200 之间，默认值为 54。如果你设置了超出范围的值，极狐GitLab 会自动调整为默认值。

项目徽章

维护者或拥有者可以为项目添加徽章，并在项目的 概览 页面上可见。如果发现需要为多个项目添加相同的徽章，可能希望在群组级别添加它们。

示例项目徽章：流水线状态

常见项目徽章呈现极狐GitLab CI 流水线状态。

要将此徽章添加到项目：

  1. 在左侧边栏上，选择 搜索或转到 并找到你的项目。
  2. 选择 设置 > 常规。
  3. 展开 徽章。
  4. 在 名称 下，输入 Pipeline Status。
  5. 在 链接 下，输入以下 URL：https://gitlab.com/%{project_path}/-/commits/%{default_branch}
  6. 在 徽章图像 URL 下，输入以下 URL：https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg
  7. 选择 添加徽章。

群组徽章

拥有者可以为群组添加徽章，并在属于该群组的任何项目的 概览 页面上可见。通过为群组添加徽章，你可以为群组中的所有项目添加并强制执行项目级徽章。

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

虽然这些徽章在代码库中显示为项目级徽章，但它们不能在项目级进行编辑或删除。

{{< /alert >}}

如果需要每个项目的独立徽章，可以：

查看徽章

查看项目或群组中可用的徽章：

  1. 在左侧边栏上，选择 搜索或转到 并找到你的项目或群组。
  2. 选择 设置 > 常规。
  3. 展开 徽章。

添加徽章

向项目或群组添加新徽章：

  1. 在左侧边栏上，选择 搜索或转到 并找到你的项目或群组。
  2. 选择 设置 > 常规。
  3. 展开 徽章。
  4. 选择 添加徽章。
  5. 在 名称 文本框中，输入徽章的名称。
  6. 在 链接 文本框中，输入徽章应指向的 URL。
  7. 在 徽章图像 URL 文本框中，输入要显示的徽章图像的 URL。
  8. 选择 添加徽章。

查看流水线徽章的 URL

你可以查看徽章的确切链接。然后你可以使用链接将徽章嵌入到 HTML 或 Markdown 页面中。

  1. 在左侧边栏上，选择 搜索或转到 并找到你的项目。
  2. 选择 设置 > CI/CD。
  3. 展开 常规流水线。
  4. 在 流水线状态、覆盖率报告或最新发布部分，查看图像的 URL。

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

流水线状态徽章基于特定的极狐GitLab 修订（分支）。确保选择适当的分支以查看正确的流水线状态。

{{< /alert >}}

自定义徽章

你可以自定义徽章的以下方面：

  • 样式
  • 文本
  • 宽度
  • 图像

自定义徽章样式

通过在 URL 中添加 style=style_name 参数，流水线徽章可以以不同样式呈现。提供两种样式：

  • 扁平（默认）：

    https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat

  • 扁平方形：

    https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square

自定义徽章文本

徽章的文本可以自定义，以区分在同一流水线中运行的多个覆盖率作业。通过在 URL 中添加 key_text=custom_text 和 key_width=custom_key_width 参数，来自定义徽章文本和宽度：

https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130

自定义徽章图像

如果希望使用默认徽章以外的徽章，可以在项目或群组中使用自定义徽章图像。

前提条件：

  • 一个直接指向徽章所需图像的有效 URL。如果图像位于极狐GitLab 仓库中，请使用图像的原始链接。

使用占位符，这里是一个引用仓库根目录中原始图像的示例徽章图像 URL：

https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg

要向群组或项目添加具有自定义图像的新徽章：

  1. 在左侧边栏上，选择 搜索或转到 并找到你的项目或群组。
  2. 选择 设置 > 常规。
  3. 展开 徽章。
  4. 在 名称 下，输入徽章的名称。
  5. 在 链接 下，输入徽章应指向的 URL。
  6. 在 徽章图像 URL 下，输入直接指向应显示的自定义图像的 URL。
  7. 选择 添加徽章。

要了解如何使用流水线生成的自定义图像，请参阅关于通过 URL 访问最新作业产物的文档。

编辑徽章

编辑项目或群组中的徽章：

  1. 在左侧边栏上，选择 搜索或转到 并找到你的项目或群组。
  2. 选择 设置 > 常规。
  3. 展开 徽章。
  4. 在要编辑的徽章旁边，选择 编辑 ({{< icon name=”pencil” >}})。
  5. 编辑 名称、链接或 徽章图像 URL。
  6. 选择 保存更改。

删除徽章

删除项目或群组中的徽章：

  1. 在左侧边栏上，选择 搜索或转到 并找到你的项目或群组。
  2. 选择 设置 > 常规。
  3. 展开 徽章。
  4. 在要删除的徽章旁边，选择 删除 ({{< icon name=”remove” >}})。
  5. 在确认对话框中，选择 删除徽章。

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

与群组关联的徽章只能在群组级别编辑或删除。

{{< /alert >}}

占位符

徽章指向的 URL 和图像 URL 都可以包含占位符，在显示徽章时进行评估。可用的占位符如下：

  • %{project_path}: 包含父群组的项目路径
  • %{project_title}: 项目标题
  • %{project_name}: 项目名称
  • %{project_id}: 与项目关联的数据库 ID
  • %{project_namespace}: 项目的项目命名空间
  • %{group_name}: 项目的群组
  • %{gitlab_server}: 项目的服务器
  • %{gitlab_pages_domain}: 托管极狐GitLab Pages 的域名
  • %{default_branch}: 项目仓库配置的默认分支名称
  • %{commit_sha}: 项目仓库默认分支的最近提交 ID
  • %{latest_tag}: 项目仓库中添加的最新标签

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

占位符允许徽章公开否则私密的信息，例如项目配置为私有仓库时的默认分支或提交 SHA。这种行为是有意为之，因为徽章旨在公开使用。如果信息敏感，请避免使用这些占位符。

{{< /alert >}}