gitlab-badge

徽章技能

使用 glab api 原始端点调用管理 GitLab 项目徽章。

快速参考

操作	命令模式	风险
列出徽章	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	-

风险说明：- 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况使用：

• 用户提及“徽章”“状态徽章”或“覆盖率徽章”
• 用户想要在 README 中添加徽章
• 用户想要流水线或构建状态指示器
• 用户提及徽章链接或徽章图片

以下情况切勿使用：

• 用户想要为议题/MR 添加标签（使用 gitlab-label）
• 用户想要查看流水线状态（使用 gitlab-ci）
• 用户想要管理项目设置（使用 gitlab-repo）

API 前提条件

必需的令牌作用域： api

权限：

• 读取徽章：Reporter 及以上
• 管理徽章：Maintainer 及以上

徽章占位符

GitLab 支持在徽章 URL 中使用占位符：

占位符	描述
%{project_path}	完整项目路径（例如：group/project）
%{project_id}	数字形式的项目 ID
%{project_name}	项目名称
%{project_namespace}	项目命名空间
%{default_branch}	默认分支名称
%{commit_sha}	当前提交 SHA

可用命令

列出项目徽章

# List all project badges
glab api projects/123/badges --method GET

# Using project path
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/badges"

列出群组徽章

# List group badges (inherited by projects)
glab api groups/456/badges --method GET

获取徽章详情

# Get specific badge
glab api projects/123/badges/1 --method GET

创建徽章

# 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"

# 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"

# Create custom badge (e.g., 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"

# 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"

# 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"

更新徽章

# Update badge URLs
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"

删除徽章

# Delete badge
glab api projects/123/badges/1 --method DELETE

预览徽章渲染效果

# 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

常见徽章模板

流水线状态徽章

# Link and image URLs
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}/-/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"

发布徽章

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"

自定义 Shields.io 徽章

# 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"

# 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"

# 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"

常见工作流

工作流 1：设置标准徽章

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"

# 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"

# 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"

工作流 2：生成 README 徽章 Markdown

# Get all badges and generate markdown
glab api projects/123/badges | \
  jq -r '.[] | "[![\(.name // "badge")](\(.rendered_image_url))](\(.rendered_link_url))"'

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

source_project=123
target_project=456

# Get badges from source
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

工作流 4：审查徽章配置

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

工作流 5：替换所有徽章

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

# 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"

故障排除

问题	原因	解决方案
徽章未显示	URL 不正确	检查 API 响应中的渲染后 URL
403 Forbidden	不是 Maintainer	需要 Maintainer 或更高角色
占位符未替换	语法错误	使用 %{placeholder} 格式
覆盖率徽章显示“unknown”	没有覆盖率报告	配置 CI 输出覆盖率
流水线徽章显示旧状态	缓存	徽章图片可能已被缓存

徽章最佳实践

1. 使用占位符：让徽章能够在不同项目间移植
2. 为徽章命名：便于在列表中识别徽章
3. 链接到相关页面：点击徽章后应跳转到有用的页面
4. 保持徽章更新：移除过时的徽章
5. 采用一致的样式：混用 GitLab 和 shields.io 徽章可能显得不协调

相关文档

• API 助手
• 安全防护措施
• 快速参考
• GitLab 徽章 API