バッジ

バッジは、プロジェクトに関する情報を凝縮して表示する統一された方法です。バッジは、小さな画像とその画像が指す URL で構成されます。GitLabでは、バッジはプロジェクトの説明の下に表示されます。バッジはプロジェクトや グループレベルで使うことができます。

Badges on Project information page

利用できるバッジ

GitLabは以下のパイプラインバッジを提供しています：

GitLab はカスタムバッジもサポートしています。

パイプラインステータスバッジ

パイプラインステータスバッジは、プロジェクトの最新のパイプラインのステータスを示します。パイプラインのステータスによって、バッジの値は次のいずれかになります：

  • pending
  • running
  • passed
  • failed
  • skipped
  • manual
  • canceled
  • unknown

パイプライン ステータス バッジのイメージには、次のリンクからアクセスできます：

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg

スキップされないステータスのみを表示

パイプラインステータスのバッジに、最後にスキップされなかったステータスのみを表示するには、?ignore_skipped=true クエリパラメータを使用します：

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true

テストカバレッジレポートのバッジ

テストカバレッジレポートのバッジは、プロジェクトでテストされたコードの割合を示します。この値は、成功した最新のパイプラインに基づいて計算されます。

以下のリンクから、テストカバレッジレポートのバッジ画像にアクセスできます：

https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg

各ジョブのログが照合されるカバレッジレポートの正規表現を定義できます。つまり、パイプラインの各ジョブにテストカバレッジのパーセンテージ値を定義できます。

特定のジョブのカバレッジレポートを取得するには、job=coverage_job_name パラメータを URL に追加します。たとえば、coverage ジョブのテストカバレッジレポートバッジを Markdown ファイルに追加するには、次のようなコードを使用します：

![coverage](https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?job=coverage)

テストカバレッジレポートバッジの色と制限

バッジのデフォルトの色と制限は以下のとおりです：

  • 95 から 100% まで - 良い (#4c1)
  • 90 から 95% まで - 可 (#a3c51c)
  • 75 から 90% - 中程度 (#dfb317)
  • 0 から 75% - 低 (#e05d44)
  • 補償なし - 不明 (#9f9f9f)
note
up toは、上限までという意味です。

以下の追加パラメータを使うことで制限を上書きすることができます（GitLab 14.4で導入）：

  • min_good (デフォルトは 95、3 から 100 の間で任意の値を使用できます)
  • min_acceptable (デフォルト90、2からmin_good-1の間の任意の値を使用可能)
  • min_medium (デフォルト75、1からmin_acceptable-1の間の任意の値を使用可能)

無効な境界が設定された場合、GitLabは自動的に有効な境界となるように調整します。例えば、min_good が80 に設定され、min_acceptable が85 (高すぎる) に設定された場合、GitLab は自動的にmin_acceptable を79 (min_good -1) に設定します。

最新のリリースバッジ

GitLab 14.8で導入されました。

最新リリースバッジは、プロジェクトの最新リリースタグ名を示します。リリースがない場合は、none と表示されます。

以下のリンクから最新リリースバッジの画像にアクセスできます：

https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg

デフォルトでは、バッジは?order_by クエリパラメータでreleased_at 時刻でソートされたリリースを取得します。

https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at

value_width パラメータを使ってリリース名フィールドの幅を変更することができます（GitLab 15.10 で導入）。値は1から200の間で、デフォルト値は54です。範囲外の値を設定した場合、GitLabは自動的にデフォルト値に調整します。

プロジェクトのバッジ

バッジはメンテナーやオーナーがプロジェクトに追加することができ、プロジェクトの概要ページに表示されます。複数のプロジェクトに同じバッジを追加する必要がある場合、グループレベルで追加するとよいでしょう。

プロジェクトにバッジを追加します。

プロジェクトに新しいバッジを追加するには：

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定] > [全般]を選択します。
  3. バッジ] を展開します。
  4. バッジを追加]を選択します。
  5. リンク]の下に、バッジが指すURLを入力します。
  6. バッジ画像のURL］には、表示する画像のURLを入力します。
  7. バッジを追加]を選択します。

プロジェクトにバッジを追加すると、フォームの下のリストにバッジが表示されます。

プロジェクトバッジの編集・削除

バッジを編集するには、編集（{鉛筆}）を選択します。

バッジを削除するには、削除({remove}) を選択します。

プロジェクトバッジの例：パイプラインステータス

一般的なプロジェクトバッジはGitLab CIパイプラインのステータスを表示します。

このバッジをプロジェクトに追加するには

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. 設定] > [全般]を選択します。
  3. バッジ] を展開します。
  4. 名前] の下に [パイプラインステータス] を入力します。
  5. リンク］に次のURLを入力します：https://gitlab.com/%{project_path}/-/commits/%{default_branch}
  6. バッジ画像のURL」の下に、以下のURLを入力します：https://gitlab.com/%{project_path}/badges/%{default_branch}/pipeline.svg
  7. バッジを追加]を選択します。

グループバッジ

グループにバッジを追加すると、グループ内のすべてのプロジェクトにプロジェクトレベルのバッジが追加されます。グループバッジは、そのグループに属するプロジェクトの概要ページに表示されます。

note
これらのバッジは、コードベースではプロジェクトレベルのバッジとして表示されますが、プロジェクトレベルでは編集や削除ができません。

プロジェクトごとに個別のバッジが必要な場合は、次のどちらかを行ってください：

グループにバッジを追加します。

グループに新しいバッジを追加するには：

  1. 左のサイドバーで、Search（検索）を選択するか、Go to（移動）を選択してグループを探します。
  2. 設定] > [全般]を選択します。
  3. バッジ] を展開します。
  4. リンク」にバッジが指すURLを入力し、「バッジ画像URL」に表示する画像のURLを入力します。
  5. バッジを追加]を選択します。

グループにバッジを追加すると、フォームの下のリストに表示されます。

グループバッジの編集・削除

バッジを編集するには、編集（{鉛筆}）を選択します。

バッジを削除するには、削除({remove}) を選択します。

グループに関連付けられたバッジは、グループレベルでのみ編集または削除できます。

パイプラインバッジのURLを表示

バッジの正確なリンクを見ることができます。そのリンクを使って、HTMLやMarkdownページにバッジを埋め込むことができます。

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. 一般的なパイプラインを拡大する。
  4. パイプラインステータス]、[カバレッジレポート]、または[最新リリース]セクションで、画像の URL を表示します。

Pipelines badges

バッジのカスタマイズ

バッジの以下の部分をカスタマイズすることができます：

  • スタイル
  • テキスト
  • 幅
  • イメージ

バッジスタイルのカスタマイズ

パイプラインバッジは、style=style_name パラメータを URL に追加することで、さまざまなスタイルで表示することができます。2つのスタイルがあります：

  • フラット (デフォルト)：

     https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat

    Badge flat style

  • フラットな正方形(GitLab 11.8で導入)：

     https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square

    Badge flat square style

バッジテキストのカスタマイズ

GitLab 13.1で導入されました。

同じパイプラインで実行される複数のカバレッジジョブを区別するために、バッジのテキストをカスタマイズすることができます。key_text=custom_text とkey_width=custom_key_width パラメータを URL に追加することで、バッジのテキストと幅をカスタマイズできます：

https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130

Badge with custom text and width

バッジ画像のカスタマイズ

デフォルト以外のバッジを使いたい場合は、プロジェクトやグループでカスタムバッジイメージを使用してください。

前提条件：

  • バッジの画像を直接指す有効なURL。画像が GitLab リポジトリにある場合は、画像への生のリンクを使用してください。

プレースホルダを使ったバッジ画像の URL の例です。リポジトリのルートにある生の画像を参照します：

https://gitlab.example.com/<project_path>/-/raw/<default_branch>/my-image.svg

グループやプロジェクトにカスタム画像付きの新しいバッジを追加するには：

  1. 左サイドバーで、検索を選択するか、プロジェクトまたはグループを検索します。
  2. 設定] > [全般]を選択します。
  3. バッジ] を展開します。
  4. 名前] にバッジの名前を入力します。
  5. リンクの下に、バッジが指すURLを入力します。
  6. バッジ画像URLの下に、表示するカスタム画像を直接指すURLを入力します。
  7. バッジを追加]を選択します。

パイプラインを通じて生成されたカスタムイメージを使用する方法については、URLによる最新ジョブのアーティファクトへのアクセスに関するドキュメントを参照してください。

プレースホルダ

バッジが指し示すURLと画像のURLには、バッジを表示する際に評価されるプレースホルダを含めることができます。以下のプレースホルダが使用可能です：

  • %{project_path}:親グループを含むプロジェクトのパス。
  • %{project_title}:プロジェクトのタイトル
  • %{project_name}:プロジェクト名
  • %{project_id}:プロジェクトに関連するデータベースID
  • %{default_branch}:プロジェクトのリポジトリに設定されているデフォルトのブランチ名。
  • %{commit_sha}:プロジェクトのリポジトリのデフォルトブランチへの直近のコミットの ID。
note
プレースホルダーを使うと、プロジェクトが非公開リポジトリに設定されている場合に、デフォルトブランチや SHA のような非公開情報をバッジに公開することができます。バッジは公開するものなので、この挙動は意図的なものです。機密性の高い情報である場合は、これらのプレースホルダーを使用しないようにしてください。

API を使ったバッジの設定

GitLab API を使ってバッジを設定することもできます。設定のように、バッジのエンドポイントはプロジェクトレベルとグループレベルで区別されています。