SonarQubeとは｜静的解析ツールの使い方と品質ゲート運用

SonarQubeとは｜静的解析でコード品質を可視化する仕組み

SonarQubeは、ソースコードを実行せずに解析して問題箇所を検出し、プロジェクト全体の品質状態をダッシュボードで可視化するツールです。解析結果はサーバー側に蓄積され、コミットやプルリクエストのたびに更新されます。単発のチェックではなく、継続的な品質の推移を見る基盤だと捉えると役割がつかみやすくなります。

何を検出するのか

検出対象は大きく3つの領域に分かれます。

これに加えて、セキュリティホットスポットという区分があります。これは「危険かどうかは文脈次第なので、人が判断してほしい」という扱いの箇所です。自動で欠陥と断定せず、レビュー待ちとして積まれます。ここを理解していないと「警告が消えない」と誤解しがちです。

テストカバレッジや重複率といったメトリクスも集約されます。ただしカバレッジはSonarQubeが測るわけではありません。JaCoCoやIstanbulといったカバレッジツールが出力したレポートを読み込んで表示する形です。この勘違いは導入初期に非常に多く見られます。

MQRモードとStandard Experienceの違い

ここは2025年以降にSonarQubeを触る人がつまずきやすい論点です。

従来のSonarQubeは、ルールを「バグ」「脆弱性」「コードスメル」の3タイプに分類し、1ルールにつき1つの重大度を割り当てていました。これが Standard Experience です。

一方の MQR（Multi-Quality Rule）モード は、1つのルールが複数の品質領域に与える影響をそれぞれ別の重大度で表します。たとえば、ある問題が保守性には大きく、信頼性には軽く効く、といった表現ができます。公式ドキュメントを2026年11月11日時点で確認した限りでは、新規に構築したSonarQube Serverインスタンスは MQRモードが既定 で、バージョン10.1以前からアップグレードした既存インスタンスはStandard Experienceが既定になると案内されています（Multi-Quality Rule mode）。既定値は改定されうるため、実機の管理画面で現在の設定を確認してください。

参画先の画面と手元の検証環境で表示が違う場合、まずこのモード設定を疑ってください。管理画面のConfiguration配下で切り替えられます。

現在の製品名と旧名の対応

日本語で検索すると、旧名で書かれた記事が今も多くヒットします。Sonar社が製品名をSonarQubeブランドに統一したのは2024年10月で、それ以前の記事はすべて旧名表記です。読み替えの対応表を頭に入れておくと、情報を取り違えずに済みます。

Community Buildは名称変更とあわせてバージョン体系も変わり、年月ベースの表記で月次リリースされる形になりました。執筆時点では長期サポート版（LTA）の指定が置かれておらず、最新版のみが現行扱いです。アップグレードの頻度を自分たちで吸収できるかは、セルフホストを選ぶ前に確認しておきたい点になります。名称整理の経緯はSonar社の製品名整理に関するアナウンスを参照してください。

ESLintやSemgrepとの違い

役割が重なるようで、実はレイヤーが違います。

ESLintやRuboCopのようなリンターは、1ファイル単位・手元での即時フィードバックが得意です。SonarQubeは、プロジェクト横断の状態をサーバーに蓄積し、履歴と基準で判定するのが本質です。前者は書いている最中、後者はマージ判断の場面で効きます。

セキュリティ側のツールとも補完関係にあります。SAST・DAST・SCAの整理はSAST・DAST・SCAの違い｜Semgrep／Snykで始めるセキュア開発で詳しく扱っているため、脆弱性検知の設計はそちらを参照してください。本記事は品質管理側に絞ります。

AIによるレビュー支援と並べて検討されることも増えました。こちらはAIコードレビュー導入ガイド｜主要6ツール比較と人間レビューの分担で比較しています。静的解析は決定的な判定、AIレビューは文脈を読んだ提案と、使いどころを分けると衝突しません。

ミニFAQ：ESLintを入れているならSonarQubeは不要ですか。

目的が違うため、置き換えにはなりません。ただしリソースが限られるなら、まずリンターを整備し、複数リポジトリの状態を一元管理したくなった段階でSonarQubeを検討する順序が現実的です。

エディションの違いと選び方

結論から書くと、1人〜小規模でmainブランチの状態だけ見たいならCommunity Build、プルリクエスト単位で止めたいならDeveloper Edition以降です。ここが最大の分岐点になります。

Community Buildでできること・できないこと

Community Buildは無料で、セルフホストで動きます。対応言語数は、執筆時点でCommunity Build向け公式ドキュメントが40以上、Sonar公式の製品ページ（ServerとCloudを含む表記）が45以上と案内しており、同じ「SonarQube」でも参照先によって数字が異なります。数を根拠に提案するときは、どのエディションのどのページを見た数字かを添えてください。小さなプロジェクトであれば、Community Buildでも十分に実用的です。

一方で、フィーチャーブランチの解析とプルリクエスト解析・PR装飾は含まれません。つまり「PRにSonarQubeがコメントを付けて、基準を満たさなければマージを止める」という、多くの人が期待する運用はCommunity Buildだけでは成立しません。解析できるのは実質的にメインブランチの状態です。

この制約を知らずに提案すると、導入後に「思っていたものと違う」となります。ブランチ解析・PR装飾・taint分析といった機能の境界は導入判断に直結し、誤ると見積りごと崩れます。提案の前に、公式のFeature comparison tableで必ず現時点の線引きを確認してください。本記事の記述は2026年11月11日時点の同ページの内容に基づいています。

有償版で増えるもの

Serverではなくマネージドで済ませたい場合はSonarQube Cloudという選択肢もあります。CIからトークンを渡すだけで動くため、インフラ管理の工数を払いたくないチームには向きます。料金体系は改定されるため、提案時は必ず公式の料金ページで最新を確認してください。本記事では金額を固定して書きません。

選定フロー

実務では次の順で潰すと早く決まります。

1. プルリクエスト単位で止める必要があるか。必要ならDeveloper Edition以降、またはCloud

2. ソースコードを外部に出せるか。出せないならServer、問題なければCloudも候補

3. 対象リポジトリは1つか複数か。複数部署をまたいで集計したいならEnterprise

4. 運用担当を置けるか。置けないならCloud寄り

ミニFAQ：Community Buildでブランチ解析を実現する方法はありますか。

有志が公開しているコミュニティプラグインは存在します。ただしSonar社のサポート対象外で、特定バージョンにしか対応しないものが多く、アップグレードのたびに追随が必要です。参画先の本番運用に入れる場合は、保守責任が誰に残るかを先に合意してください。

品質ゲートとは｜Sonar wayの4条件

品質ゲートは、解析結果に対して「この基準を満たさなければリリース可とみなさない」と宣言する仕組みです。SonarQubeを単なる可視化ツールで終わらせず、運用の歯止めに変えるのがこの機能になります。

既定の品質ゲートは「Sonar way」という名前です。公式ドキュメントを2026年11月11日時点で確認したところ、次の4条件で構成されていました。条件の構成やしきい値はバージョンやエディション、インスタンスのモード設定によって異なる場合があるため、自分のインスタンスの画面で実際の条件を確認するのが確実です。

なぜ「新規コード」だけなのか

4条件すべてが新規コードを対象にしている点が重要です。これは Clean as You Code という考え方に基づいています。

既存コードの負債を一気に返そうとすると、作業量が読めず、途中で止まります。そこで判定の対象を「今回追加・変更した部分」に限定し、触った箇所だけはきれいにする。これを続ければ、コードベース全体は時間とともに改善されていきます。

この設計思想を理解しないまま「全体のカバレッジ80%」を条件にすると、既存プロジェクトでは初日から赤になり、誰も見なくなります。失敗の典型です。技術的負債そのものの扱いについては技術的負債とは｜リファクタリング案件の合意形成と単価への影響が参考になります。

参画先に合わせた調整の考え方

Sonar wayをそのまま使うべきか、緩めるべきか。判断は対象プロジェクトの状況によります。

• テストコードがほぼ無い既存プロジェクト：カバレッジ条件は最初から80%にせず、段階的に引き上げる合意を取る

• 新規立ち上げ：Sonar wayのまま入れてよい。最初がいちばん厳しくできる

• 保守フェーズで改修が小さい：重複率より、セキュリティホットスポットのレビュー率を優先する

カスタムの品質ゲートは複製して作るのが安全です。既定のSonar wayを直接編集すると、他プロジェクトに影響します。

ミニFAQ：品質ゲートが赤でもマージできてしまいます。

SonarQube側のゲートは判定を出すだけです。マージを物理的に止めるには、GitHubやGitLabの必須ステータスチェックとして登録する設定が別途必要になります。ここの接続漏れは非常に多いポイントです。

導入手順｜Dockerでの起動からCI連携まで

ローカル検証であれば、Dockerで立ち上げて最初の解析結果が出るまで 1〜2時間程度 を見ておくと無理がありません。対象リポジトリの規模やビルド時間で変わるため、あくまで目安として扱ってください。

ステップ1：サーバーを起動する

もっとも手軽なのはDockerです。公式イメージを使い、ホストのポート9000をコンテナの9000に割り当てて起動します。コマンドは docker run -d --name sonarqube -p 9000:9000 sonarqube:community の形になります。

ここで1点だけ注意があります。SonarQubeは内部でElasticsearchを使うため、Linuxではカーネルパラメータの vm.max_map_count を 262144以上 に設定しておく必要があります。これを忘れると起動直後にコンテナが落ち、ログを見るまで原因がわかりません。

検証を超えて継続利用するなら、データベースをPostgreSQLに分離し、ボリュームを永続化してください。コンテナ内蔵のDBは評価用です。Dockerそのものの基礎はDockerとは？コンテナ技術の仕組みとできること｜案件762件で見る単価相場で確認できます。

ステップ2：プロジェクト作成とトークン発行

ブラウザで localhost:9000 を開き、初期アカウント（admin / admin）でログインします。初回ログイン時にパスワード変更を求められます。

ログイン後、プロジェクトを手動作成し、解析用のトークンを発行します。このトークンはCIの環境変数として渡すため、必ずシークレットとして保管してください。リポジトリに直書きすると、そのまま漏洩経路になります。

ステップ3：スキャナーを実行する

解析はSonarScannerが担当します。言語によって使うスキャナーが変わる点に注意してください。

• Java（Maven / Gradle）：ビルドツールのプラグイン経由で実行する

• JavaScript / TypeScript / Python / Go など：SonarScanner CLIを使う

• C / C++ / Objective-C：ビルドラッパーを併用する

CLIを使う場合は、リポジトリ直下に sonar-project.properties を置き、プロジェクトキーとソースディレクトリを書きます。この設定ファイルを置かずにCIで実行すると、解析対象が空のまま成功扱いになることがあります。

ステップ4：CIに組み込む

GitHub Actionsであれば、SonarSourceが提供する公式アクションをワークフローに追加し、トークンとサーバーURLをシークレットとして渡します。解析ステップのあとに品質ゲート判定のステップを置けば、基準を満たさないときにジョブを失敗させられます。

CI側の基礎は、使っているツールに応じて次を参照してください。

• GitHub Actionsとは？CI/CDの仕組み・基本ワークフロー・案件単価をフリーランス視点で解説

• Jenkinsとは？CI/CDの仕組み・GitHub Actionsとの違い・案件動向をフリーランス視点で解説

• GitLab CIとは｜.gitlab-ci.ymlの書き方・料金・GitHub Actionsとの違いと案件動向

• Azure DevOpsとは｜GitHubとの違い・料金と案件での使い方

ステップ5：カバレッジレポートを連携する

前述のとおり、カバレッジはSonarQubeが計測しません。テスト実行時にJaCoCo（Java）、lcov（JavaScript / TypeScript）、coverage.py（Python）などでレポートを出力し、そのパスをSonarQubeに指定します。

この連携を飛ばすと、ダッシュボード上のカバレッジが0%のまま張り付きます。そして品質ゲートのカバレッジ条件が永久に満たせなくなります。導入初期の相談でいちばん多いのが、この設定漏れです。

既存プロジェクトに後から導入する進め方

新規プロジェクトへの導入は簡単です。難しいのは、すでに数年動いているコードベースに後入れするケースで、フリーランスが頼まれるのはたいていこちらです。

既存プロジェクトでCIに組み込み、品質ゲートでプルリクエストを止められる状態にするまでは、2〜4週間程度 を見ておくと安全です。これは技術作業そのものより、チームの合意形成と例外ルールの調整に時間がかかるためです。規模や体制によって変わるため、固定の工数として扱わないでください。

フェーズ1：観測だけする（最初の1週間）

品質ゲートは設定せず、解析だけ回します。既存コードにどれだけの指摘が積まれるのかを、チーム全員が数字で見る期間です。ここでいきなりゲートを有効にすると、全員が赤を見て思考停止します。

フェーズ2：新規コードに限定してゲートを入れる（2週目以降）

Clean as You Codeの考え方どおり、判定対象を新規コードに絞ってゲートを有効化します。既存の指摘は残したまま、新しく書く部分だけを縛ります。このときカバレッジのしきい値は、チームの現状に合わせて下げた値から始めてもかまいません。

フェーズ3：しきい値を段階的に上げる

運用が回り始めてから、カバレッジや重複率のしきい値を引き上げます。引き上げのタイミングはスプリントの区切りに合わせると、合意が取りやすくなります。

レビュー文化そのものが未整備な現場では、ツール導入より先に進め方の整理が要ります。コードレビューの作法｜指摘の書き方・受け方と信頼される進め方を併せて読むと、提案の順序を組み立てやすくなるはずです。

よくある失敗と対策

失敗1：既存コードの大量指摘で放置される

数万件の指摘が出て、誰も開かなくなるパターン。対策は前述のフェーズ分割です。新規コードだけに絞り、既存分は「見えているが今は対象外」と明示的に位置づけます。

失敗2：CIが遅くなって敬遠される

全ブランチ・全コミットで重い解析を走らせると、CIの待ち時間が伸びます。プルリクエスト時とメインブランチへのマージ時に限定する、キャッシュを効かせる、といった調整で体感は大きく変わります。

失敗3：カバレッジが0%のまま

ステップ5の連携漏れです。レポートの出力パスと、SonarQubeに指定したパスが一致しているかを最初に確認してください。CI上の作業ディレクトリと相対パスの食い違いが典型的な原因になります。

失敗4：Community BuildにPR装飾を期待する

エディションの章で触れたとおりです。提案前に機能表を確認し、必要なら予算の話を先に出してください。後出しになると信用を落とします。

失敗5：ルールを無効化しすぎる

指摘が多いからといってルールを次々オフにすると、残るのは何も言わないダッシュボードです。無効化ではなく、重大度の調整や品質プロファイルの分離で対応するほうが後戻りしやすくなります。

フリーランスエンジニアの案件での関わり方

SonarQubeそのものを対策キーワードにした募集は多くありません。実際には、CI/CD構築、開発基盤整備、品質改善といった案件の構成要素として登場します。

求められる役割

• CI/CDパイプラインの構築・改善の一環としてのツール選定と導入

• 既存プロジェクトへの品質ゲート導入と、チームへの浸透設計

• 複数リポジトリの品質状態を集約するダッシュボード整備

いずれも「ツールを入れられる」だけでは足りません。導入後に運用が続く形まで設計できるかが評価の分かれ目になります。失敗パターンを先回りして潰せる人は重宝されます。

提案を通すための順序

参画先で導入を提案するなら、次の順で話すと通りやすくなります。

1. 現状の課題を数値で示す（レビュー指摘の手戻り件数、本番障害の原因分類など）

2. 無料のCommunity Buildで観測だけ始める案を出す

3. 1か月後、実データをもとに有償版が要るかを判断する

最初から有償版の稟議を通そうとすると止まります。観測フェーズを挟む提案は、決裁の負担が小さく、こちらの実績も残ります。

案件選びの優先順位づけ全般は案件の選び方｜フリーランスエンジニアが単価・稼働・スキルで決める優先順位で整理しています。品質・テスト側の実績をスキルシートにどう書くかはQAエンジニアのスキルシートの書き方｜品質実績の数値化と職種別テンプレが参考になります。

単価は案件の職責やフェーズで変わるため、ツール名だけで決まるものではありません。自分の経験でどのくらいのレンジを狙えるか把握しておきたい方は、無料のフリーランスエンジニア単価診断で市場単価の目安を確認できます。CI/CD基盤に関わる案件を探す場合は、Jenkinsを含む開発環境の案件一覧や案件一覧から条件を絞り込めます。

導入チェックリスト

参画先で導入を任されたときに、そのまま使える確認項目です。

導入前

• プルリクエスト単位で止める必要があるか（有償版の要否が決まる）

• ソースコードを外部サービスに置けるか（Server / Cloudの分岐）

• 解析対象の言語とスキャナーの組み合わせを確認したか

• カバレッジを出すツールがすでに入っているか

構築時

• vm.max_map_countを262144以上に設定したか

• データベースを分離し、ボリュームを永続化したか

• トークンをCIのシークレットとして登録したか（リポジトリに直書きしていないか）

• sonar-project.propertiesのソースディレクトリ指定が正しいか

運用開始時

• 最初の1週間は観測のみに留めたか

• 品質ゲートの対象を新規コードに絞ったか

• カバレッジのしきい値をチームの現状に合わせたか

• GitHub / GitLab側の必須ステータスチェックに登録したか

• インスタンスのモード（MQR / Standard Experience）をチームで共有したか

まとめ

SonarQubeは、コードを実行せずに品質とセキュリティの問題を可視化し、品質ゲートでリリース判断を自動化するための基盤です。ツールを入れること自体は難しくありません。難所は、既存コードの負債をどう扱い、チームに運用を定着させるかにあります。

• 検出対象はセキュリティ・信頼性・保守性の3領域。セキュリティホットスポットは人のレビューを前提とする別区分

• 2024年10月以降の名称は Server / Cloud / Community Build / for IDE。旧名の記事を読むときは読み替える

• 無料のCommunity Buildにブランチ解析とPR装飾は含まれない。ここが有償版との最初の分岐

• 既定の品質ゲート「Sonar way」は新規コード対象の4条件（問題0件、ホットスポットのレビュー100%、カバレッジ80%以上、重複3.0%以下）

• 既存プロジェクトへの後入れは、観測のみ → 新規コードに限定してゲート → 段階的にしきい値を上げる、の3フェーズで進める

• カバレッジはSonarQubeが測らない。レポート連携の設定漏れが初期トラブルの筆頭

• 提案は「無料で観測から」が通りやすい。有償版の判断は実データが出てから

次の一歩としては、手元のリポジトリでDockerからCommunity Buildを立ち上げ、実際にどれだけの指摘が出るかを見てみてください。数字を持っていると、参画先での提案の説得力が変わります。

参照した一次情報は以下のとおりです。

• SonarQube 製品ページ（Sonar公式）

• Understanding quality gates（公式ドキュメント）

• Multi-Quality Rule mode（公式ドキュメント）

• Feature comparison table（SonarQube Community Build 公式ドキュメント）

• 製品名の整理に関するアナウンス（Sonar公式）

• Plans and pricing（Sonar公式）