Back to Details

gitlab-badge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Badge Skill

Badge 技能

Project badge management for GitLab using 
glab api
raw endpoint calls.
使用
glab api
原始端点调用进行GitLab项目徽章管理。

Quick Reference

快速参考

OperationCommand PatternRisk
List badges
glab api projects/:id/badges
-
Get badge
glab api projects/:id/badges/:badge_id
-
Create badge
glab api projects/:id/badges -X POST -f ...
⚠️
Update badge
glab api projects/:id/badges/:badge_id -X PUT -f ...
⚠️
Delete badge
glab api projects/:id/badges/:badge_id -X DELETE
⚠️
Preview badge
glab api projects/:id/badges/render?...
-
List group badges
glab api groups/:id/badges
-
Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger
操作命令格式风险
列出徽章
glab api projects/:id/badges
-
获取徽章详情
glab api projects/:id/badges/:badge_id
-
创建徽章
glab api projects/:id/badges -X POST -f ...
⚠️
更新徽章
glab api projects/:id/badges/:badge_id -X PUT -f ...
⚠️
删除徽章
glab api projects/:id/badges/:badge_id -X DELETE
⚠️
预览徽章
glab api projects/:id/badges/render?...
-
列出群组徽章
glab api groups/:id/badges
-
风险说明: - 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

何时使用本技能

ALWAYS use when:
  • User mentions "badge", "status badge", "coverage badge"
  • User wants to add badges to README
  • User wants pipeline or build status indicators
  • User mentions badge links or badge images
NEVER use when:
  • User wants labels on issues/MRs (use gitlab-label)
  • User wants status of pipelines (use gitlab-ci)
  • User wants project settings (use gitlab-repo)
务必在以下场景使用:
  • 用户提及"badge"、"状态徽章"、"覆盖率徽章"
  • 用户想要为README添加徽章
  • 用户需要流水线或构建状态指示器
  • 用户提及徽章链接或徽章图片
请勿在以下场景使用:
  • 用户想要为议题/合并请求添加标签（使用gitlab-label技能）
  • 用户想要查看流水线状态（使用gitlab-ci技能）
  • 用户想要修改项目设置（使用gitlab-repo技能）

API Prerequisites

API 前置条件

Required Token Scopes: 
api
Permissions:
  • Read badges: Reporter+
  • Manage badges: Maintainer+
所需令牌权限范围: 
api
权限要求:
  • 读取徽章：Reporter及以上角色
  • 管理徽章：Maintainer及以上角色

Badge Placeholders

徽章占位符

GitLab supports placeholders in badge URLs:
PlaceholderDescription
%{project_path}
Full project path (e.g., 
group/project
)
%{project_id}
Numeric project ID
%{project_name}
Project name
%{project_namespace}
Project namespace
%{default_branch}
Default branch name
%{commit_sha}
Current commit SHA
GitLab支持在徽章URL中使用占位符：
占位符描述
%{project_path}
完整项目路径（例如：
group/project
）
%{project_id}
数字项目ID
%{project_name}
项目名称
%{project_namespace}
项目命名空间
%{default_branch}
默认分支名称
%{commit_sha}
当前提交SHA值

Available Commands

可用命令

List Project Badges

列出项目徽章

bash
undefined
bash
undefined

List all project badges

列出所有项目徽章

glab api projects/123/badges --method GET
glab api projects/123/badges --method GET

Using project path

使用项目路径

glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/badges"
undefined
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/badges"
undefined

List Group Badges

列出群组徽章

bash
undefined
bash
undefined

List group badges (inherited by projects)

列出群组徽章（会被项目继承）

glab api groups/456/badges --method GET
undefined
glab api groups/456/badges --method GET
undefined

Get Badge Details

获取徽章详情

bash
undefined
bash
undefined

Get specific badge

获取指定徽章

glab api projects/123/badges/1 --method GET
undefined
glab api projects/123/badges/1 --method GET
undefined

Create Badge

创建徽章

bash
undefined
bash
undefined

Create pipeline status badge

创建流水线状态徽章

glab api projects/123/badges --method POST
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
glab api projects/123/badges --method POST
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"

Create coverage badge

创建覆盖率徽章

glab api projects/123/badges --method POST
-f link_url="https://gitlab.com/%{project_path}/-/jobs"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/coverage.svg"
glab api projects/123/badges --method POST
-f link_url="https://gitlab.com/%{project_path}/-/jobs"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/coverage.svg"

Create custom badge (e.g., shields.io)

创建自定义徽章（例如：shields.io）

glab api projects/123/badges --method POST
-f link_url="https://opensource.org/licenses/MIT"
-f image_url="https://img.shields.io/badge/License-MIT-yellow.svg"
glab api projects/123/badges --method POST
-f link_url="https://opensource.org/licenses/MIT"
-f image_url="https://img.shields.io/badge/License-MIT-yellow.svg"

Create named badge

创建带名称的徽章

glab api projects/123/badges --method POST
-f name="Build Status"
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
glab api projects/123/badges --method POST
-f name="Build Status"
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"

Create release badge

创建版本发布徽章

glab api projects/123/badges --method POST
-f link_url="https://gitlab.com/%{project_path}/-/releases"
-f image_url="https://gitlab.com/%{project_path}/-/badges/release.svg"
undefined
glab api projects/123/badges --method POST
-f link_url="https://gitlab.com/%{project_path}/-/releases"
-f image_url="https://gitlab.com/%{project_path}/-/badges/release.svg"
undefined

Update Badge

更新徽章

bash
undefined
bash
undefined

Update badge URLs

更新徽章URL

glab api projects/123/badges/1 --method PUT
-f link_url="https://new-link.com"
-f image_url="https://new-image.com/badge.svg"
glab api projects/123/badges/1 --method PUT
-f link_url="https://new-link.com"
-f image_url="https://new-image.com/badge.svg"

Update badge name

更新徽章名称

glab api projects/123/badges/1 --method PUT
-f name="New Badge Name"
undefined
glab api projects/123/badges/1 --method PUT
-f name="New Badge Name"
undefined

Delete Badge

删除徽章

bash
undefined
bash
undefined

Delete badge

删除徽章

glab api projects/123/badges/1 --method DELETE
undefined
glab api projects/123/badges/1 --method DELETE
undefined

Preview Badge Rendering

预览徽章渲染效果

bash
undefined
bash
undefined

Preview how a badge would render

预览徽章渲染效果

glab api "projects/123/badges/render?link_url=https://gitlab.com/%{project_path}&image_url=https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg" --method GET
undefined
glab api "projects/123/badges/render?link_url=https://gitlab.com/%{project_path}&image_url=https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg" --method GET
undefined

Common Badge Templates

常用徽章模板

Pipeline Status Badge

流水线状态徽章

bash
undefined
bash
undefined

Link and image URLs

链接和图片URL

link_url="https://gitlab.com/%{project_path}/-/pipelines" image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
glab api projects/123/badges --method POST
-f link_url="$link_url"
-f image_url="$image_url"

Markdown: `[![pipeline status](https://gitlab.com/group/project/badges/main/pipeline.svg)](https://gitlab.com/group/project/-/pipelines)`
link_url="https://gitlab.com/%{project_path}/-/pipelines" image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
glab api projects/123/badges --method POST
-f link_url="$link_url"
-f image_url="$image_url"

Markdown格式：`[![pipeline status](https://gitlab.com/group/project/badges/main/pipeline.svg)](https://gitlab.com/group/project/-/pipelines)`

Coverage Badge

覆盖率徽章

bash
link_url="https://gitlab.com/%{project_path}/-/jobs"
image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/coverage.svg"

glab api projects/123/badges --method POST \
  -f link_url="$link_url" \
  -f image_url="$image_url"
bash
link_url="https://gitlab.com/%{project_path}/-/jobs"
image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/coverage.svg"

glab api projects/123/badges --method POST \
  -f link_url="$link_url" \
  -f image_url="$image_url"

Release Badge

版本发布徽章

bash
link_url="https://gitlab.com/%{project_path}/-/releases"
image_url="https://gitlab.com/%{project_path}/-/badges/release.svg"

glab api projects/123/badges --method POST \
  -f link_url="$link_url" \
  -f image_url="$image_url"
bash
link_url="https://gitlab.com/%{project_path}/-/releases"
image_url="https://gitlab.com/%{project_path}/-/badges/release.svg"

glab api projects/123/badges --method POST \
  -f link_url="$link_url" \
  -f image_url="$image_url"

Custom Shields.io Badges

自定义Shields.io徽章

bash
undefined
bash
undefined

License badge

许可证徽章

glab api projects/123/badges --method POST
-f name="License"
-f link_url="https://opensource.org/licenses/MIT"
-f image_url="https://img.shields.io/badge/License-MIT-blue.svg"
glab api projects/123/badges --method POST
-f name="License"
-f link_url="https://opensource.org/licenses/MIT"
-f image_url="https://img.shields.io/badge/License-MIT-blue.svg"

Version badge

版本徽章

glab api projects/123/badges --method POST
-f name="Version"
-f link_url="https://gitlab.com/%{project_path}/-/releases"
-f image_url="https://img.shields.io/badge/version-1.0.0-green.svg"
glab api projects/123/badges --method POST
-f name="Version"
-f link_url="https://gitlab.com/%{project_path}/-/releases"
-f image_url="https://img.shields.io/badge/version-1.0.0-green.svg"

Maintenance badge

维护状态徽章

glab api projects/123/badges --method POST
-f name="Maintained"
-f link_url="https://gitlab.com/%{project_path}"
-f image_url="https://img.shields.io/badge/Maintained%3F-yes-green.svg"
undefined
glab api projects/123/badges --method POST
-f name="Maintained"
-f link_url="https://gitlab.com/%{project_path}"
-f image_url="https://img.shields.io/badge/Maintained%3F-yes-green.svg"
undefined

Common Workflows

常见工作流

Workflow 1: Set Up Standard Badges

工作流1：设置标准徽章

bash
project_id=123
bash
project_id=123

Pipeline status

流水线状态

glab api projects/$project_id/badges --method POST
-f name="Pipeline"
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
glab api projects/$project_id/badges --method POST
-f name="Pipeline"
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"

Coverage

覆盖率

glab api projects/$project_id/badges --method POST
-f name="Coverage"
-f link_url="https://gitlab.com/%{project_path}/-/jobs"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/coverage.svg"
glab api projects/$project_id/badges --method POST
-f name="Coverage"
-f link_url="https://gitlab.com/%{project_path}/-/jobs"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/coverage.svg"

Latest release

最新版本

glab api projects/$project_id/badges --method POST
-f name="Release"
-f link_url="https://gitlab.com/%{project_path}/-/releases"
-f image_url="https://gitlab.com/%{project_path}/-/badges/release.svg"
undefined
glab api projects/$project_id/badges --method POST
-f name="Release"
-f link_url="https://gitlab.com/%{project_path}/-/releases"
-f image_url="https://gitlab.com/%{project_path}/-/badges/release.svg"
undefined

Workflow 2: Generate README Badge Markdown

工作流2：生成README徽章Markdown代码

bash
undefined
bash
undefined

Get all badges and generate markdown

获取所有徽章并生成Markdown代码

glab api projects/123/badges |
jq -r '.[] | "(.name // "badge")))"'
undefined
glab api projects/123/badges |
jq -r '.[] | "(.name // "badge")))"'
undefined

Workflow 3: Copy Badges to Another Project

工作流3：将徽章复制到另一个项目

bash
source_project=123
target_project=456
bash
source_project=123
target_project=456

Get badges from source

从源项目获取徽章

badges=$(glab api projects/$source_project/badges)
badges=$(glab api projects/$source_project/badges)

Create in target (using placeholders, so they'll work for the new project)

在目标项目创建徽章（使用占位符，确保在新项目中可用）

echo "$badges" | jq -c '.[]' | while read badge; do link_url=$(echo "$badge" | jq -r '.link_url') image_url=$(echo "$badge" | jq -r '.image_url') name=$(echo "$badge" | jq -r '.name // empty')
glab api projects/$target_project/badges --method POST
-f link_url="$link_url"
-f image_url="$image_url"
${name:+-f name="$name"} done
undefined
echo "$badges" | jq -c '.[]' | while read badge; do link_url=$(echo "$badge" | jq -r '.link_url') image_url=$(echo "$badge" | jq -r '.image_url') name=$(echo "$badge" | jq -r '.name // empty')
glab api projects/$target_project/badges --method POST
-f link_url="$link_url"
-f image_url="$image_url"
${name:+-f name="$name"} done
undefined

Workflow 4: Audit Badge Configuration

工作流4：审计徽章配置

bash
undefined
bash
undefined

List all badges with rendered URLs

列出所有徽章及渲染后的URL

glab api projects/123/badges |
jq -r '.[] | "ID: (.id)\n Name: (.name // "unnamed")\n Image: (.rendered_image_url)\n Link: (.rendered_link_url)\n"'
undefined
glab api projects/123/badges |
jq -r '.[] | "ID: (.id)\n Name: (.name // "unnamed")\n Image: (.rendered_image_url)\n Link: (.rendered_link_url)\n"'
undefined

Workflow 5: Replace All Badges

工作流5：替换所有徽章

bash
project_id=123
bash
project_id=123

Delete existing badges

删除现有徽章

glab api projects/$project_id/badges | jq -r '.[].id' | while read badge_id; do glab api projects/$project_id/badges/$badge_id --method DELETE done
glab api projects/$project_id/badges | jq -r '.[].id' | while read badge_id; do glab api projects/$project_id/badges/$badge_id --method DELETE done

Create new badges

创建新徽章

glab api projects/$project_id/badges --method POST
-f name="Build"
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
undefined
glab api projects/$project_id/badges --method POST
-f name="Build"
-f link_url="https://gitlab.com/%{project_path}/-/pipelines"
-f image_url="https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg"
undefined

Troubleshooting

故障排除

IssueCauseSolution
Badge not showingURL incorrectCheck rendered URLs in API response
403 ForbiddenNot maintainerNeed Maintainer+ role
Placeholder not replacedWrong syntaxUse 
%{placeholder}
format
Coverage badge shows "unknown"No coverage reportConfigure CI to output coverage
Pipeline badge shows old statusCacheBadge images may be cached
问题原因解决方案
徽章不显示URL错误检查API响应中的渲染后URL
403 禁止访问非Maintainer角色需要Maintainer及以上角色
占位符未被替换语法错误使用
%{placeholder}
格式
覆盖率徽章显示“unknown”无覆盖率报告配置CI以输出覆盖率数据
流水线徽章显示旧状态缓存徽章图片可能被缓存

Badge Best Practices

徽章最佳实践

  1. Use placeholders: Make badges portable between projects
  2. Name your badges: Helps identify them in the list
  3. Link to relevant pages: Badge clicks should go somewhere useful
  4. Keep badges updated: Remove stale badges
  5. Use consistent styling: Mix of GitLab and shields.io can look inconsistent
  1. 使用占位符：让徽章在不同项目间可移植
  2. 为徽章命名：便于在列表中识别
  3. 链接到相关页面：点击徽章应跳转到有用的页面
  4. 保持徽章更新：移除过时的徽章
  5. 使用统一样式：混合使用GitLab和shields.io徽章可能导致样式不一致

Related Documentation

相关文档