Help us learn about your current experience with the documentation. Take the survey.

标题：徽章

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

徽章是一种统一的方式来展示项目信息的浓缩片段。 徽章由一个小型图片和图片指向的 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)

测试覆盖率限制和徽章颜色

下表显示了默认的测试覆盖率限制和徽章颜色：

测试覆盖率 百分比限制 徽章颜色
Good 95 到 100%（含） ■ #4c1
Acceptable 90 到 95% ■ #a3c51c
Medium 75 到 90% ■ #dfb317
Low 0 到 75% ■ #e05d44
Unknown 无覆盖率 ■ #9f9f9f

Up to 表示达到但不包括上限。

更改默认限制

您可以通过在覆盖率报告徽章 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

默认情况下，徽章使用 released_at 时间对版本进行排序，并使用 ?order_by 查询参数。

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

您可以使用 value_width 参数更改版本名称字段的宽度（在 GitLab 15.10 中引入）。 该值必须在 1 到 200 之间，默认值为 54。 如果您设置了超出范围的值，GitLab 会自动将其调整为默认值。

项目徽章

徽章可以由 Maintainers 或 Owners 添加到项目中，并显示在项目的 Overview 页面上。 如果您发现需要在多个项目中添加相同的徽章，可能需要将其添加到 群组级别。

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

常见的项目徽章展示 GitLab CI 流水线状态。

要将此徽章添加到项目中：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。
  2. 选择 Settings > General。
  3. 展开 Badges。
  4. 在 Name 下，输入 Pipeline Status。
  5. 在 Link 下，输入以下 URL： https://gitlab.com/%{project_path}/-/commits/%{default_branch}
  6. 在 Badge image URL 下，输入以下 URL： https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg
  7. 选择 Add badge。

群组徽章

徽章可以由 Owners 添加到群组中，并显示在属于该群的任何项目的 Overview 页面上。 通过向群组添加徽章，您可以为群组中的所有项目添加并强制执行项目级徽章。

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

如果需要为每个项目使用单独的徽章，可以：

查看徽章

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

  1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
  2. 选择 Settings > General。
  3. 展开 Badges。

添加徽章

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

  1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
  2. 选择 Settings > General。
  3. 展开 Badges。
  4. 选择 Add badge。
  5. 在 Name 文本框中，输入您的徽章名称。
  6. 在 Link 文本框中，输入徽章应指向的 URL。
  7. 在 Badge image URL 文本框中，输入您要为徽章显示的图片 URL。
  8. 选择 Add badge。

查看流水线徽章的 URL

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

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。
  2. 选择 Settings > CI/CD。
  3. 展开 General pipelines。
  4. 在 Pipeline status、Coverage report 或 Latest release 部分，查看图片的 URL。

流水线状态徽章基于特定的 Git 版本（分支）。请确保选择适当的分支以查看正确的流水线状态。

自定义徽章

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

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

自定义徽章样式

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

  • Flat（默认）：

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

    Badge flat style

  • Flat square：

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

    Badge flat square style

自定义徽章文本

徽章文本可以自定义，以区分同一流水线中运行的多个覆盖率作业。 通过向 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

Badge with custom text and width

自定义徽章图片

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

先决条件：

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

使用占位符，以下是引用存储库根目录原始图片的示例徽章图片 URL：

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

要将带有自定义图片的新徽章添加到群组或项目：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目或 群组。
  2. 选择 Settings > General。
  3. 展开 Badges。
  4. 在 Name 下，输入徽章的名称。
  5. 在 Link 下，输入徽章应指向的 URL。
  6. 在 Badge image URL 下，输入应显示的自定义图片的直接指向 URL。
  7. 选择 Add badge。

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

编辑徽章

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

  1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
  2. 选择 Settings > General。
  3. 展开 Badges。
  4. 在要编辑的徽章旁边，选择 Edit（ pencil ）。
  5. 编辑 Name、Link 或 Badge image URL。
  6. 选择 Save changes。

删除徽章

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

  1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
  2. 选择 Settings > General。
  3. 展开 Badges。
  4. 在要删除的徽章旁边，选择 Delete（ remove ）。
  5. 在确认对话框中，选择 Delete badge。

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

占位符

徽章指向的 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}：添加到项目仓库的最新标签

占位符允许徽章暴露其他敏感信息，例如当项目配置为私有仓库时的默认分支或提交 SHA。这种设计是故意的，因为徽章旨在公开使用。如果信息敏感，请避免使用这些占位符。