sonar-quality-gate

Name: sonar-quality-gate
Author: sonarsource

github.com/sonarsourceテスト・品質11452 回インストール今日更新

sonar-quality-gate について

sonar-quality-gate は、SonarQube プロジェクトの品質ゲートを評価する Skill です。全体ステータスと各条件を確認でき、失敗条件の詳細を得るため sonar CLI を優先し、特定の場合に SonarQube MCP ツールへフォールバックします。

主な機能

01品質ゲート全体の状態を報告
02API が返す全条件を一覧表示
03失敗条件の詳細を可能な場合に表示
04ブランチまたはプルリクエストで絞り込み
05CLI の状態取得ができない場合に MCP ツールへフォールバック

活用シーン

01現在のプロジェクトが品質ゲートを通過するか確認
02プロジェクトやブランチのゲート条件を確認
03失敗条件の主な要因を特定

MCP 対応

CLI の品質ゲートコマンドが使えない場合、SonarQube MCP ツールでプロジェクトのゲート状態を取得できます。MCP の応答には状態と条件が含まれますが、CLI の詳細な内訳は含まれません。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/sonarsource/sonarqube-agent-plugins --skill sonar-quality-gate

インストール後、Claude Code で/sonar-quality-gateを入力して読み込まれたか確認します。

詳細

SonarQube — 品質ゲート

SonarQube プロジェクトの品質ゲート評価のみを報告します。全体のステータス、API が返すすべての条件、および失敗した条件についての最悪値の内訳を含めてください。ここで幅広いメトリクスのダッシュボードを取得しないでください。ゲート以外の数値メトリクス（カバレッジ％、イシュー数、メジャーとしての評価など）については、必要な metricKeys を指定して、後から**mcp__sonarqube__get_component_measures**を使用してください。

使用方法

sonar-quality-gate                       # quality gate for the current project
sonar-quality-gate my-project            # quality gate for a specific project key
sonar-quality-gate my-project --branch release/2.0
sonar-quality-gate my-project --pr 42

前提条件

このスキルでは、主な方法として sonarqube-cli コマンド sonar quality-gate status（エイリアスは sonar qg status）を使用します。他の方法を作り出さないでください（例：sonar mcp call は存在しません）。MCP ツールよりもこちらを優先してください。CLI は失敗した条件ごとの最悪値の内訳を同じ呼び出しで返します（ステップ 5 を参照）が、MCP ツールではその詳細を得るために別途呼び出し（メジャー、イシュー）が必要です。

続行する前に、sonar が PATH 上で利用可能で、認証済みであることを確認してください。インストールされていない、または認証されていない場合、MCP のフォールバックも役に立ちません。SonarQube MCP Server 自体が sonar run mcp で起動され、CLI に保存された認証情報を共有するためです（sonar-integrate スキルを通じてセットアップされていれば常に該当します。ただし、独自のトークンを使うスタンドアロンの Docker コンテナーなどを使って sonarqube MCP サーバーを個別に設定した場合は該当しません）。そのため、以下のメッセージにすぐ進み、sonar-integrate スキルを推奨してください。sonar は動作するものの quality-gate status 自体が利用できない場合（古い CLI でサブコマンドが不明な場合や、別の理由でコマンドがエラーになる場合）に限り、ステップ 3 で MCP ツール mcp__sonarqube__get_project_quality_gate_status にフォールバックしてください。

MCP のフォールバックも失敗した場合（たとえば、ツールが利用できない場合やプロジェクトキーを解決できない場合）は、原因を絞り込んでください。このエージェントの設定で sonarqube MCP サーバーが有効になっているか確認してください。

有効になっていない／登録されていない → sonar-integrate スキルの実行を推奨します。
有効になっているが、ツールがまだ利用できない → 設定は正しいものの、サーバーの起動に失敗しています。最も一般的な原因は、コンテナーランタイムが起動していないことです。MCP サーバーは sonar run mcp を通じて Docker／Podman／Nerdctl 内で起動するため、デーモンが停止していると、正しく設定されていてもツールが利用できません。docker ps を実行し（失敗した場合は podman ps／nerdctl ps を実行して）、どの原因に該当するか確認してください。エラーになる場合、ランタイムが停止しています。ユーザーが起動した後、エージェントセッションの再起動を依頼する前に、同じコマンドが成功することを確認してください。

いずれの場合も、ユーザーに次の内容を表示してください。

sonar quality-gate status の実行、SonarQube MCP Server への接続、またはプロジェクトキーの解決ができませんでした。

考えられる原因：

sonarqube-cli がインストールされていない、または認証されていない — sonar-integrate スキルを実行してください

MCP サーバーが登録されていない — sonar-integrate スキルを実行して SonarQube MCP Server を設定し、その後エージェントセッションを再起動してください

コンテナーランタイムが起動していない — SonarQube MCP Server はコンテナー（Docker、Podman、または Nerdctl）内で動作します。コンテナーランタイムを起動し、その後エージェントセッションを再起動してください

認証情報が設定されていない — sonar-integrate スキルを実行してください

プロジェクトキーが誤っている、または MCP 設定にデフォルトのプロジェクトがない — 明示的なキーを渡すか、sonar-project.properties を確認するか、このプロジェクトで sonar-integrate スキルを再実行してください

続けて、今すぐ sonar-integrate スキルを実行するかどうか、ユーザーに「はい／いいえ」で尋ねてください。そのスキルで何を行うか簡潔に説明してください。ユーザーのマシン上の SonarQube 設定を確認し、sonarqube-cli のインストールまたは更新と認証の検証を行い、SonarQube MCP サーバーやシークレットスキャンのフックを含め、このエージェント向けの連携を再設定します。ユーザーが同意した場合は、自分で sonar-integrate スキルを呼び出して、このセッション内で最初から最後まで実行してください。その後、新しい MCP ツールを利用できるように、コンテナーランタイム（Docker、Podman、または Nerdctl）が起動していることを確認し、エージェントセッションを再起動するようユーザーに依頼してください。ユーザーが断った場合は、そこで終了してください。

手順

ステップ 1：プロジェクトキーを解決する（必要な場合のみ）

sonar quality-gate status では -p は不要です。sonar list issues（-p が必須）とは異なり、-p が指定されていない場合は、sonar-project.properties の sonar.projectKey からプロジェクトを解決します。キーの解決が必要なのは、キーを渡す必要がある場合（ユーザーが別のプロジェクトを指定している場合、またはステップ 3 で MCP ツールにフォールバックし、そのスキーマでキーが必須の場合）のみです。

ユーザーがプロジェクトキーを指定している場合は、それを使用します。
指定されていない場合は、リポジトリのルートにある sonar-project.properties で sonar.projectKey を探します。
それでも見つからない場合、CLI では -p を省略して自動解決に任せます。MCP にフォールバックする場合は、projectKey を省略し、代わりに統合のデフォルト値を使用します。

ステップ 2：ユーザーが指定した引数からオプションのフィルターを解析する

フラグ	CLI オプション	MCP パラメーター（フォールバック時）
`--branch <name>`	`--branch`	`branchKey`
`--pr <id>`	`--pull-request`	`pullRequestKey`

--branch と --pr は相互に排他的です。ユーザーが両方を指定した場合は、どちらの意味か確認してください。指定されていないフラグ／キーは省略します。MCP ツールで異なるパラメーター名が使われている場合は、SonarQube MCP サーバーが公開するスキーマに従ってください。

ステップ 3：`sonar quality-gate status` を実行する

コマンドを実行する前に、補間する値を検証してください。プロジェクトキーは ^[a-zA-Z0-9_\-\.:]+$、--branch は ^[a-zA-Z0-9_\-\./]+$、--pull-request は数字のみ（sonar-list-issues スキルと同じルール）である必要があります。いずれかの値が条件を満たさない場合は、コマンドを実行せず、拒否した値をユーザーに伝えてください。

sonar quality-gate status [-p <project-key>] [--branch <name> | --pull-request <id>] --format json

必ず --format json を使用して解析してください。CLI のデフォルトの table 出力をそのままユーザーに伝えず、解析結果をステップ 4 の形式に従って整えてください。

このコマンドは、トップレベルの status（OK、ERROR、またはサーバーが使用するその他の値）と、conditions 配列を返します。各条件には通常、次の項目が含まれます。

フィールド	意味
`metricKey`	ゲート条件の SonarQube メトリクス識別子
`status`	条件ごとの結果（`OK`、`ERROR`、…）
`errorThreshold`	ゲートで定義されている場合に必要な境界値（一部の種類では存在しない場合があります）
`actualValue`	SonarQube がしきい値と比較した値

対応する新しい CLI では、同じ呼び出しで失敗した条件ごとに breakdown も返されます。別途取得せず、ステップ 5 を参照してください。breakdown がない場合は、エラーではなく「利用できない」として扱ってください。

例（すべての条件が OK） — レスポンスの形式：

{
  "status": "OK",
  "conditions": [
    {
      "metricKey": "reliability_rating",
      "status": "OK",
      "errorThreshold": "2",
      "actualValue": "1"
    },
    {
      "metricKey": "security_rating",
      "status": "OK",
      "errorThreshold": "1",
      "actualValue": "1"
    },
    {
      "metricKey": "new_duplicated_lines_density",
      "status": "OK",
      "errorThreshold": "3",
      "actualValue": "0.0"
    }
  ]
}

例（ゲート失敗） — 一部の条件で errorThreshold がないのは通常の状態です。

{
  "status": "ERROR",
  "conditions": [
    {
      "metricKey": "new_coverage",
      "status": "ERROR",
      "errorThreshold": "85",
      "actualValue": "82.50562381034781"
    },
    {
      "metricKey": "new_blocker_violations",
      "status": "ERROR",
      "errorThreshold": "0",
      "actualValue": "14"
    },
    {
      "metricKey": "new_sqale_debt_ratio",
      "status": "OK",
      "errorThreshold": "5",
      "actualValue": "0.6562109862671661"
    },
    {
      "metricKey": "reopened_issues",
      "status": "OK",
      "actualValue": "0"
    },
    {
      "metricKey": "open_issues",
      "status": "ERROR",
      "actualValue": "17"
    }
  ]
}

sonar quality-gate status 自体を利用できない場合（古い CLI で未知のサブコマンドと表示される場合、または CLI が見つからない／認証されていないこと以外の理由でコマンドが失敗する場合）は、mcp__sonarqube__get_project_quality_gate_status にフォールバックしてください。 sonar がインストールされていない、または認証されていない場合は、MCP ツールを試さないでください。MCP サーバーは sonar run mcp 経由で実行され、CLI の認証情報を共有するため、こちらも利用できません。ただし、sonarqube MCP サーバーが独立して設定されている場合（たとえば、独自のトークンを持つスタンドアロンの Docker コンテナーを使用している場合）は、MCP ツールが動作する可能性があるため、試してください。その場合は「前提条件」にメッセージを表示し、代わりに sonar-integrate を推奨してください。ステップ 1 で解決した projectKey があり、かつ ツールがそれを必要とする場合に限り、projectKey を含めてください。それ以外の場合は省略し、統合のデフォルトに任せてください。ペイロードの例：

{
  "projectKey": "<only-if-required>",
  "branchKey": "<name, if --branch was given>",
  "pullRequestKey": "<id, if --pr was given instead>"
}

branchKey は --branch が指定された場合にのみ含め、pullRequestKey は --pr が指定された場合にのみ含めてください。両方を同時に含めてはいけません（ステップ 2 を参照）。統合のデフォルトが適用される場合は、ペイロードから projectKey を省略してください。使用しないキーは省略してください。

このツールは上記と同じ status／conditions の形式を返しますが、breakdown はありません。ステップ 5 を参照してください。

Step 4: 結果を整形する

簡潔なレポートを提示します。

見出し — トップレベルの status を平易な表現に置き換えます（例：OK → 合格、ERROR → 失敗）。プロジェクトキーと、判明している場合はブランチ／PR の情報を含めます。
条件テーブル — conditions の各要素につき1行を設け、最低限、次の列を含めます。
- メトリクス — metricKey（名称が分かる場合は軽く分かりやすくし、それ以外はキーをそのまま使用します）。
- 条件のステータス — status。
- しきい値 — errorThreshold がある場合はその値、ない場合は — を使用します。
- 実際の値 — actualValue がある場合はその値、ない場合は — を使用します。

失敗した条件（サーバーのルールに従い、ERROR または OK 以外）を、合格した条件より前に並べます。

評価 — reliability_rating／security_rating などのキーについて、SonarQube では API 内の評価が数値のグレードとして表されることがよくあります（例：1 = A、5 = E）。ユーザーの理解に役立つ場合は、その解釈について説明します。
追加メトリクスは取得しない — 同じターンでユーザーがより詳細なメトリクスを明示的に求めていない限り、このスキル内で get_component_measures を呼び出さないでください。詳細が必要な場合は、次のステップを案内します（Step 6 を参照）。
内訳（CLI 経由の場合のみ） — 条件に breakdown が含まれている場合（Step 3 の主要な CLI 経由の方法で、新しいバージョンの CLI を使用している場合）、その条件の行の下に、カテゴリに関連するフィールドを使った短いインデント付きリストとして表示します（カテゴリごとの形式については Step 5 を参照）。breakdown がない場合、または MCP のフォールバックを使用している場合は、内訳を表示しません。

quality gate のペイロードがない場合、または分析が実行されていない場合は、値を作り出さず、そのことを明確に伝えます。

ステップ 5：失敗した条件をカテゴリ別に扱う

失敗したゲート条件は、通常、単なる平坦なリストではありません。失敗した各条件を、その指標の種類に応じて扱ってください。プライマリ CLI パスでは、ほぼ追加の手間はかかりません。sonar quality-gate status は、失敗した各条件について最も問題のある項目をすでに breakdown にまとめています（この拡張がまだない古い CLI では breakdown フィールド自体がありませんが、これはエラーではなく「利用不可」と同じように扱ってください）。MCP フォールバックでは、ツールが返すのは conditions のみで、内訳はありません。以下を参考に指標キーでカテゴリ分けし、詳細については該当するスキルに引き継いでください。

失敗したカバレッジ条件の breakdown の例（CLI パス）：

{
  "metricKey": "new_coverage",
  "status": "ERROR",
  "errorThreshold": "85",
  "actualValue": "82.5",
  "breakdown": [
    { "file": "src/auth/login.py", "coverage": "42.0" },
    { "file": "src/utils/helpers.py", "coverage": "58.3" }
  ]
}

指標キーで分類します。

カバレッジ（coverage、new_coverage、branch_coverage、line_coverage、…） — breakdown には、カバレッジ率が最も低いファイルが表示されます。最もテストが必要なファイルをユーザーに伝えてください。特定のファイルの行単位の詳細については、sonar-coverage に引き継いでください。
重複（duplicated_lines_density、new_duplicated_lines_density、duplicated_blocks、…） — breakdown には、重複ブロック数と重複先のファイルがそれぞれ示された、重複の多いファイルが表示されます。共通ヘルパーの抽出を提案してください。重複ブロック全体については、sonar-duplication に引き継いでください。
イシューとセキュリティ（violations、bugs、code_smells、reliability_rating、sqale_rating／new_maintainability_rating、および対応する十分新しい CLI では vulnerabilities／security_rating） — breakdown には失敗の原因となったイシュー自体（ファイル、行、キー、ルール、メッセージ）が表示されるため、通常はそのまま対応できます。さらに広い条件で絞り込む場合（重要度、ステータス、その他のファイルなど）は、sonar-list-issues に引き継いでください。
依存関係のリスク（sca_count_*、sca_rating_*、sca_severity_* など、sca_ で始まる指標キー） — breakdown は、パッケージ／バージョン／重要度／種類の一覧で、ファイルの場所は含まれません。SCA リスクはプロジェクト単位であり、特定のファイルや行には紐づきません。これはサーバーがすでに把握している未解決のリスクを反映しています。マニフェストを新たに再スキャンする場合や、CVE レベルの詳細を確認する場合は、sonar-dependency-risks に引き継いでください。

プライマリ CLI パスで特定のカテゴリだけを確認する必要がある場合（たとえば、ユーザーが「カバレッジが失敗した理由は？」と具体的に尋ねた場合）は、sonar quality-gate status を --category <coverage|duplications|issues|dependency-risks> 付きで再実行します（値は上記の指標グループに対応します。サポート状況は CLI のバージョンによって異なります）。--top <n> で、各 breakdown に含める項目数を指定できます。ステップ 3 のように --category を省略すると、すべてのカテゴリの breakdown が一度に返されます。ユーザーから求められた場合にのみ、対象を絞り込んでください。MCP フォールバックには再実行できる CLI 呼び出しがないため、上記の該当するスキルに引き継いでください。

ステップ 6：より詳細な指標（`get_component_measures`）

ゲートの範囲を超えて調査する場合（全体のカバレッジ、行カバレッジ、バグ件数、詳細な評価など）は、該当する場合は同じブランチ／PR コンテキストを指定して mcp__sonarqube__get_component_measures を呼び出し、必要な指標を metricKeys に指定してください。projectKey を追加するのは、ツールがそれを必要とし、解決済みのキーがある場合に限ります。それ以外の場合は、統合の既定値に任せてください（失敗した metricKey の値、または SonarQube metric keys のドキュメントを起点にできます）。

ツールが利用できない場合は、sonar api にフォールバックしてください（このコマンドには解決済みのプロジェクトキーが必要です。sonar-project.properties から自動解決するステップ 3 の sonar quality-gate status とは異なります。ステップ 1 でキーを解決できなかった場合は、ユーザーに尋ねるか sonar-list-projects を呼び出し、その後は続行しないでください）。

sonar api get "/api/measures/component?component=<project-key>&metricKeys=<comma-separated-keys>[&branch=<name>][&pullRequest=<id>]"

これも失敗した場合は、上記の標準メッセージを表示してください。これ以上のコマンドを推測しないでください。

ステップ 7：関連スキル

ステップ 5 の内訳で得られた情報を超える詳細が必要な場合にのみ使用します。

sonar-list-issues — 重大度やステータスで課題／セキュリティ検出結果を絞り込んだり、すでに表示されている上位の項目以外を確認したりします。
sonar-coverage — 特定のファイルの行ごとのカバレッジ詳細を確認します。
sonar-duplication — 特定のファイルの重複ブロック全体を確認します。
sonar-dependency-risks — 依存関係リスクのスキャンを新たに実行したり、CVE の詳細を詳しく確認したりします。

Markdown 対応

ログインしてコメント

基本情報

作者: sonarsource
リポジトリ: sonarsource/sonarqube-agent-plugins
カテゴリ: テスト・品質
インストール数: 52
GitHub スター: 114

問題を報告