CNB Docs

English

简体中文

English

简体中文
简体中文

Appearance

Badges

Copy page

About 2153 wordsAbout 7 min

Badges display metric data, using color to indicate whether standards are met.

When to use: when you want build status visible at a glance on a repository homepage or an external page — for example embedding build status or test coverage badges in a README.

Badge Access Path

Badge access paths for cloud native builds:

  • precise: https://cnb.build/{group}/{repository}/-/badge/git/{sha}/{metrics}

  • latest: https://cnb.build/{group}/{repository}/-/badge/git/latest/{metrics}

  • branch latest: https://cnb.build/{group}/{repository}/-/badge/git/latest/{metrics}?branch={branch}

  • Parameter descriptions:

    • group: Organization path of the repository
    • repository: Repository name
    • sha: First 8 characters of the CommitId
    • latest: When branch is not specified, fetches the badge for the latest default branch commit; when specified, fetches the badge for the latest commit of that branch
    • metrics: Metric name, e.g., ci/status/push, representing the build time triggered by push events
    • branch: Branch name, e.g., main, only effective when sha is latest

Badge Types

During cloud native builds, badge data for build metrics is automatically reported:

1. Git Events

ci/status/push

Push event build time and status

push eventpush eventpush event

ci/status/commit.add

Commit add event build time and status

commit.add eventcommit.add eventcommit.add event

ci/status/branch.create

Branch create event build time and status

branch.create eventbranch.create eventbranch.create event

ci/status/pull_request

Pull request event build time and status

pull_request eventpull_request eventpull_request event

ci/status/pull_request.update

Pull request update event build time and status

pull_request.update eventpull_request.update eventpull_request.update event

ci/status/pull_request.target

Pull request target event build time and status

pull_request.target eventpull_request.target eventpull_request.target event

ci/status/pull_request.merged

Pull request merged event build time and status

pull_request.merged eventpull_request.merged eventpull_request.merged event

ci/status/pull_request.approved

Pull request approved event build time and status

pr.approved eventpr.approved eventpr.approved event

ci/status/pull_request.changes_requested

Pull request changes requested event build time and status

pr.changes_requested eventpr.changes_requested eventpr.changes_requested event

ci/status/pull_request.mergeable

Pull request mergeable event build time and status

pr.mergeable eventpr.mergeable eventpr.mergeable event

ci/status/issue.comment@npc

Issue comment @npc event build time and status

issue.comment@npc eventissue.comment@npc eventissue.comment@npc event

ci/status/pull_request.comment@npc

Pull request comment @npc event build time and status

pr.comment@npc eventpr.comment@npc eventpr.comment@npc event

ci/status/tag_push

Tag push event build time and status

tag_push eventtag_push eventtag_push event

2. Workspace Preparation

ci/git-clone-yyds

Workspace size and preparation time: git-clone-yyds event

3. Pipeline Configuration

ci/pipeline-as-code

Cloud native build configuration file: pipeline-as-code event

4. Cloud Native Development

code/vscode-started

Development environment preparation time: vscode-started

5. Unit Testing

Using the built-in task testing:coverage can report unit test badge data

testing/unit/coverage

Total unit test coverage

coveragecoveragecoveragecoverage

testing/unit/coverage-pr

Incremental unit test coverage for this pull request

coverage-prcoverage-prcoverage-prcoverage-pr

6. Security

security/tca

Tencent Cloud Code Analysis (TCA): tca

7. Crontab Status

ci/status/crontab

Crontab build duration and build status

Crontab EventCrontab EventCrontab Event

8. Auto Merge

ci/status/auto_merge

Auto merge duration and status

Auto mergeAuto mergeAuto merge

Fork Badge

Display repository fork count as a badge: fork badge

Access path: https://cnb.build/{group}/{repository}/-/badge/fork

Parameter descriptions:

  • group: Repository organization path
  • repository: Repository name

Star Badge

Display repository star count as a badge: star badge

Access path: https://cnb.build/{group}/{repository}/-/badge/star

Parameter meanings:

  • group: Repository organization path
  • repository: Repository name

Deploy Badge

Display the latest deployment status and version of a repository environment:

  • With successful deployment: deploy badge
  • Without deployment record: deploy badge

Access path: https://cnb.build/{group}/{repository}/-/badge/deploy?name={name}

Click-through path: https://cnb.build/{group}/{repository}/-/badge/deploy.link?name={name}

Parameter descriptions:

  • group: Repository organization path
  • repository: Repository name
  • name: Deployment environment name (required), e.g., production, staging, etc.

Release Badge

Display the latest Release version of the repository. If a Release tag has been manually set as the Latest Release, the badge prioritizes that Release; otherwise, it defaults to the most recently created Release:

  • With Release: release badge
  • Without Release: release badge

Access path: https://cnb.build/{group}/{repository}/-/badge/release

Click-through path: https://cnb.build/{group}/{repository}/-/badge/release.link

Parameter descriptions:

  • group: Repository organization path
  • repository: Repository name

Metadata Badge

Display the value of repository metadata.

Metadata is stored as key-value pairs attached to a commit or tag. The badge label is the metadata key, and the badge message is the metadata value.

  • Metadata found: metadata badge
  • Metadata not found: metadata badge

Access Path

Commit metadata badge:

# Specific commit
https://cnb.build/{group}/{repository}/-/badge/annotation/commit/{sha}/{key}
# Latest commit of the default branch
https://cnb.build/{group}/{repository}/-/badge/annotation/commit/latest/{key}
# Latest commit of a specific branch
https://cnb.build/{group}/{repository}/-/badge/annotation/commit/latest/{key}?branch={branch}

Tag metadata badge:

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

Parameter Descriptions

  • group: Repository organization path
  • repository: Repository name
  • sha: Full commit hash
  • latest: Get the metadata of the latest commit of a branch; the default branch is used when branch is omitted
  • tag: Tag name, / is supported; URL-encode it when it contains special characters
  • key: Metadata key, e.g., reviewer; only letters, digits, _ and - are allowed, up to 64 characters
  • branch: Branch name, e.g., main, only effective when ref is latest

Extensions

Append an extension after {key} to get different content:

  • No extension: returns an SVG badge
  • {key}.json: returns the badge data as JSON
  • {key}.link: 302 redirects to the corresponding commit or tag detail page

Color Rules

  • The badge message color is derived from the metadata key in a stable way
  • The same key always gets the same color, and different keys pick colors from a dedicated palette
  • When the metadata is not found, the message is unknown and the color is grey

Security Metadata Badge

Display security scan results. The badge label is the plugin name, the message lists the issue count of each level, and the color is determined by the most severe level:

  • security badge
    security badge
  • security badge
    security badge

Access Path

# Specific commit
https://cnb.build/{group}/{repository}/-/badge/security/{plugin}/{scope}/{sha}
# Latest commit of the default branch
https://cnb.build/{group}/{repository}/-/badge/security/{plugin}/{scope}/latest
# Latest commit of a specific branch
https://cnb.build/{group}/{repository}/-/badge/security/{plugin}/{scope}/latest?branch={branch}

Parameter Descriptions

  • group: Repository organization path
  • repository: Repository name
  • sha: Full commit hash
  • latest: Get the security metadata of the latest commit of a branch; the default branch is used when branch is omitted
  • plugin: Plugin name, only the following three values are supported. See Security Scan Plugins for details
  • scope: Statistics scope, full or diff
  • branch: Branch name, e.g., main, only effective when ref is latest

Security metadata is only attached to commits, so the ref currently only supports a full commit hash or latest.

Extensions

  • No extension: returns an SVG badge
  • {sha}.json / latest.json: returns the badge data as JSON, including the issue count of each level
  • {sha}.link / latest.link: 302 redirects to the security scan report

Badge List

vulnerability/full

Full result of the Open-Source Component Vulnerability Scan, showing the vulnerability count of each severity level.

vulnerability/diff

Incremental result of the Open-Source Component Vulnerability Scan, counting only the vulnerabilities introduced by the current change.

license/full

Full result of the License Scan, showing the license count of each risk level.

license/diff

Incremental result of the License Scan, counting only the license risks introduced by the current change.

sbom/full

Full result of the SBOM Generation, showing the total component count of the current Commit.

sbom/diff

Incremental result of the SBOM Generation, showing the number of components involved in the current change.

Using Badges in Markdown

Two formats are supported for embedding badges as images in Markdown:

With domain and repository: ![Full path badge](https://cnb.build/groupname/reponame/-/badge/git/latest/ci/git-clone-yyds)

Without domain and repository: paths starting with /-/badge/git will be recognized as badges: ![Relative path badge](/-/badge/git/latest/ci/git-clone-yyds)

Embedding Badges in a README

The example below puts the latest main branch build status and unit test coverage badges at the top of the repository README, and links each badge back to the repository home page (replace groupname/reponame with the actual organization and repository name):

# Project name

[![Build status](https://cnb.build/groupname/reponame/-/badge/git/latest/ci/status/push)](
  https://cnb.build/groupname/reponame)
[![Unit test coverage](https://cnb.build/groupname/reponame/-/badge/git/latest/testing/unit/coverage)](
  https://cnb.build/groupname/reponame)

Project introduction…
  • To pin a badge to a specific commit, replace latest with the first 8 characters of that commit's sha.
  • To show a badge for another branch, append ?branch=<branch-name> to the URL.
  • The unit test coverage badge requires data reported by the testing:coverage built-in task.

Tips

The relative form without a domain (/-/badge/git/...) only works in Markdown rendered inside the platform. When the README is displayed on a third-party platform such as GitHub, use the full path with domain and repository.

© 2026 cnb.cool