gitlab-badge

バッジスキル

glab api の raw エンドポイント呼び出しを使った、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