徽章

2800 字约 9 分钟

徽章用于展示指标数据，通过颜色区分是否达标。

使用场景：想在仓库首页或外部页面直观展示构建状态时使用——例如把构建状态、单测覆盖率徽章嵌到 README，让访问者一眼看到项目当前是否健康。

云原生构建相关徽章

徽章访问路径

云原生构建徽章的访问路径：

precise：https://cnb.cool/{group}/{repository}/-/badge/git/{sha}/{metrics}
latest：https://cnb.cool/{group}/{repository}/-/badge/git/latest/{metrics}
分支 latest：https://cnb.cool/{group}/{repository}/-/badge/git/latest/{metrics}?branch={branch}
参数说明：
- group：仓库所在组织路径
- repository：仓库名
- sha：CommitId 前 8 位
- latest：未指定 branch 时，获取默认分支最新 commit 的徽章；指定 branch 时，获取该分支最新 commit 的徽章
- metrics：指标名，如 ci/status/push，表示 push 事件触发的构建耗时
branch：分支名，如 main，仅在 sha 为 latest 时生效

徽章类型

云原生构建时会报告相关构建指标的徽章数据：

1. Git 事件

`ci/status/push`

push 事件构建耗时与状态

`ci/status/commit.add`

commit.add 事件构建耗时与状态

`ci/status/branch.create`

branch.create 事件构建耗时与状态

`ci/status/pull_request`

pull_request 事件构建耗时与状态

`ci/status/pull_request.update`

pull_request.update 事件构建耗时与状态

`ci/status/pull_request.target`

pull_request.target 事件构建耗时与状态

`ci/status/pull_request.merged`

pull_request.merged 事件构建耗时与状态

`ci/status/pull_request.approved`

pull_request.approved 事件构建耗时与状态

`ci/status/pull_request.changes_requested`

pull_request.changes_requested 事件构建耗时与状态

`ci/status/pull_request.mergeable`

pull_request.mergeable 事件构建耗时与状态

`ci/status/issue.comment@npc`

issue.comment@npc 事件构建耗时与状态

`ci/status/pull_request.comment@npc`

pull_request.comment@npc 事件构建耗时与状态

`ci/status/tag_push`

tag_push 事件构建耗时与状态

2. 准备工作区

`ci/git-clone-yyds`

工作区大小与准备耗时：

3. 流水线配置

`ci/pipeline-as-code`

云原生构建的配置文件：

4. 云原生开发

`code/vscode-started`

准备开发环境耗时：

5. 单元测试

使用内置任务 testing:coverage 可上报单元测试徽章数据

`testing/unit/coverage`

单元测试全量覆盖率

`testing/unit/coverage-pr`

本次 pull_request 的单元测试增量覆盖率

6. 安全

`security/tca`

腾讯云代码分析（TCA）：

7. 定时任务

`ci/status/crontab`

定时任务构建耗时与状态

8. 自动合并

`ci/status/auto_merge`

自动合并耗时与状态

仓库相关徽章

fork 徽章

展示仓库的 Fork 数量：

访问路径：https://cnb.cool/{group}/{repository}/-/badge/fork

参数含义：

group：仓库所在组织路径
repository：仓库名

star 徽章

展示仓库的 Star 数量：

访问路径：https://cnb.cool/{group}/{repository}/-/badge/star

参数含义：

group：仓库所在组织路径
repository：仓库名

部署环境徽章

展示仓库部署环境的最新部署状态和版本：

有成功部署记录时：
无部署记录时：

访问路径：https://cnb.cool/{group}/{repository}/-/badge/deploy?name={name}

点击跳转路径：https://cnb.cool/{group}/{repository}/-/badge/deploy.link?name={name}

参数含义：

group：仓库所在组织路径
repository：仓库名
name：部署环境名称（必填），如 production、staging 等

Release 徽章

展示仓库最新 Release 的版本号。如果手动将某个 Release 的 tag 设置为最新版本（Latest Release），徽章优先展示该 Release；否则默认展示最近创建的 Release：

有 Release 时：
无 Release 时：

访问路径：https://cnb.cool/{group}/{repository}/-/badge/release

点击跳转路径：https://cnb.cool/{group}/{repository}/-/badge/release.link

参数含义：

group：仓库所在组织路径
repository：仓库名

元数据徽章

展示仓库元数据的值。元数据以键值对形式挂在 commit 或 tag 上，徽章的左侧文字为元数据 key，右侧文字为元数据 value。

命中元数据时：
未命中元数据时：

访问路径

commit 元数据徽章：

# 指定 commit
https://cnb.cool/{group}/{repository}/-/badge/annotation/commit/{sha}/{key}
# 默认分支最新 commit
https://cnb.cool/{group}/{repository}/-/badge/annotation/commit/latest/{key}
# 指定分支最新 commit
https://cnb.cool/{group}/{repository}/-/badge/annotation/commit/latest/{key}?branch={branch}

tag 元数据徽章：

https://cnb.cool/{group}/{repository}/-/badge/annotation/tag/{tag}/{key}

参数含义

group：仓库所在组织路径
repository：仓库名
sha：commit 的完整哈希值
latest：获取分支最新 commit 的元数据；未指定 branch 时取默认分支
tag：tag 名称，支持包含 /；含特殊字符时需做 URL 编码
key：元数据的键名，如 reviewer；仅支持字母、数字、_、-，最长 64 个字符
branch：分支名，如 main，仅在 ref 为 latest 时生效

扩展名

在 {key} 后追加扩展名可返回不同内容：

无扩展名：返回 SVG 徽章
{key}.json：返回徽章数据的 JSON 结构
{key}.link：302 跳转到对应的 commit 或 tag 详情页

颜色规则

徽章右侧颜色按元数据 key 稳定取色（同一 key 颜色固定，不同 key 从专用色板中取值）
未命中元数据时，右侧文字为 unknown，颜色为灰色

安全元数据徽章

展示安全扫描结果。徽章左侧为插件名，右侧为各级别问题数，颜色由最严重的级别决定：

安全徽章
安全徽章

访问路径

# 指定 commit
https://cnb.cool/{group}/{repository}/-/badge/security/{plugin}/{scope}/{sha}
# 默认分支最新 commit
https://cnb.cool/{group}/{repository}/-/badge/security/{plugin}/{scope}/latest
# 指定分支最新 commit
https://cnb.cool/{group}/{repository}/-/badge/security/{plugin}/{scope}/latest?branch={branch}

参数含义

group：仓库所在组织路径
repository：仓库名
sha：commit 的完整哈希值
latest：获取分支最新 commit 的安全元数据；未指定 branch 时取默认分支
plugin：插件名，仅支持以下三种取值，详见安全扫描插件总览
- vulnerability：开源组件漏洞扫描
- license：License 扫描
- sbom：SBOM 生成
scope：统计范围，full（全量）或 diff（增量）
branch：分支名，如 main，仅在 ref 为 latest 时生效

安全元数据只挂在 commit 上，因此目前 ref 只支持 commit 的完整哈希值或 latest。

扩展名

无扩展名：返回 SVG 徽章
{sha}.json / latest.json：返回徽章数据的 JSON 结构，含各级别问题数明细
{sha}.link / latest.link：302 跳转到安全扫描报告

徽章清单

`vulnerability/full`

开源组件漏洞扫描的全量结果，展示各严重级别的漏洞数量。

`vulnerability/diff`

开源组件漏洞扫描的增量结果，仅统计本次变更引入的漏洞。

`license/full`

License 扫描的全量结果，展示各风险级别的许可证数量。

`license/diff`

License 扫描的增量结果，仅统计本次变更引入的许可证风险。

`sbom/full`

SBOM 生成的全量结果，展示当前 Commit 的组件总数。

`sbom/diff`

SBOM 生成的增量结果，展示本次变更涉及的组件数。

在 Markdown 中使用徽章

支持以下两种格式在 Markdown 中以图片形式嵌入徽章：

带域名和仓库：![完整路径的徽章](https://cnb.cool/groupname/reponame/-/badge/git/latest/ci/git-clone-yyds)

不带域名和仓库，以 /-/badge/git 开头的会被识别为徽章：![相对路径徽章](/-/badge/git/latest/ci/git-clone-yyds)

在 README 中嵌入徽章

下面示例把 main 分支最新的构建状态、单测覆盖率徽章放到仓库 README 顶部，并让徽章点击后跳转到仓库首页（groupname/reponame 替换为实际的组织与仓库名）：

# 项目名称

[![构建状态](https://cnb.cool/groupname/reponame/-/badge/git/latest/ci/status/push)](
  https://cnb.cool/groupname/reponame)
[![单测覆盖率](https://cnb.cool/groupname/reponame/-/badge/git/latest/testing/unit/coverage)](
  https://cnb.cool/groupname/reponame)

项目简介……

需要固定某个提交的徽章时，把 latest 换成该 Commit 的前 8 位 sha。
需要其它分支的徽章时，在地址末尾追加 ?branch=<分支名>。
单测覆盖率徽章需先通过 testing:coverage 内置任务上报数据。

提示

不带域名的相对路径形式（/-/badge/git/...）只在平台内的 Markdown 渲染场景中生效；在第三方平台（如 GitHub）展示 README 时，请使用带域名和仓库的完整路径。