品質ゲート

どのようなものか

品質ゲートは、変更を次の段階へ進める前に満たす必要がある条件の集合
で、最終的な結果は合格か不合格のどちらかです。次の段階には、コミッ
ト、メインブランチへのマージ、リリース、デプロイなどがあります。条件
にできるのは、リンターの指摘がないこと、テストの合格、カバレッジの数
値、ビルドの完了など、機械が判定できるものです。

要点は、ゲートという言葉にあります。検査は結果を報告しますが、ゲート
は先へ進めるかどうかを決め、その次の手順を制御する仕組みが決定を強制
します。ログへ四十件の警告を出すリンターは、検査です。同じリンターで
も、指摘がなくなるまでマージボタンを無効に保つよう組み込めば、ゲート
の一部になります。

品質ゲートを機能名として使うSonarQube
Cloudは、解析中にコードを評価するための条件の集合と説明しています。
各条件は、メトリクス、比較演算子、エラーとする値を組み合わせます。た
とえば「信頼性の問題が0より多い」が一つの条件で、どれか一つでも満た
すとゲートは不合格になります。条件の適用先は、新しいコードか、コード
全体です。

コードのホスティングサービスも、同じ考え方をマージの流れに組み込んで
います。

  * GitHubには、ブランチ保護の設定「Require status checks before
merging」（マージ前にステータスチェックを必須とする）があります。保
護されたブランチへ変更を入れる前に、必須の検査が成功、スキップ、また
は中立のステータスを報告する必要があります。

  * GitLabには、「Pipelines must
succeed」（パイプラインの成功を必須とする）というマージ検査がありま
す。選択すると、パイプラインが失敗している間はマージリクエストをマー
ジできず、パイプラインが一つもない場合にもマージできません。

  *
開発者自身のマシンでは、pre-commitが、コミット時やプッシュ時に動く
Gitフックとして検査を組み込み、Taskなどのタスクランナーが、検査一式
を一つの名前で呼べるようにします。

なぜ重要なのか

文書の中にしかない規則は、例外のたびに交渉の対象になります。ビルドを
失敗させる規則なら、書いた本人が、その日の午後は省略したいと思ってい
ても、全員が従います。ゲートは、合意した規則を実行可能にするため、規
則を守れるかどうかが、記憶や気分に左右されなくなります。

人によるレビューの役割も変わります。機械が、書式、未使用のインポー
ト、リンク切れ、秘密情報の漏えいを既に検出していれば、レビュアーは、
機械には判断できない意図や設計へ注意を向けられます。書き手が誰でも、
求められる水準は同じです。

新しいコードに条件を適用する考え方によって、古いコードベースにもゲー
トを導入できます。SonarQube
Cloudの既定のゲートであるSonar
wayは、既存コードの修復ではなく、新しいコードを対象とします。条件に
は、新しいコードのテストカバレッジが80.0%以上であることや、重複が
3.0%以下であることなどがあります。プルリクエストでは、新しいコードに
関する条件だけを使います。既存の問題が何千件あっても、先にすべてを解
消せず、ゲートを有効にして、新しい変更の一つ一つに水準を求められま
す。

使い続けてもらえるかどうかを決めるのは、速度です。Taskは、タスクの依
存先を並行して実行するため、独立した検査を多数組み合わせたゲートで
も、順番ではなく同時に動かせます。検査をコストで分けることも役立ちま
す。軽い方の半分をコミットのたびに実行し、コードがマシンを離れる前
に、全体を実行します。

このサイトにも、独自のゲートである`task
check`があり、ホストされたビルドサービスではなく、サイトを書くマシン
上で実行します。すべての診断をエラーとし、サイトジェネレーターを
`--panicOnWarning`付きで動かすため、非推奨機能の通知だけでもビルドが
止まります。`#
noqa`や`stylelint-disable`のような行内の抑制も禁止し、失敗を黙らせる
のではなく、原因を直します。pre-commitフックは、コミットごとにファイ
ル単位の検査を実行し、pre-pushフックは、秒ではなく分単位の時間がかか
る`task
check`全体を実行します。未コミットの変更がない作業ツリーで検査に合格
すると、そのツリーに合格の印を付け、デプロイスクリプトは、印のないツ
リーを拒否します。唯一の迂回手段は、目立つ警告を表示する環境変数で
す。緊急時にゲートを省く人も、その事実を明示しなければなりません。

実際の活用例

サイトのクレジットページは、ゲートに含まれるツールを挙げています。
HTML用のvnu、Stylelint、テンプレートごとに一ページを調べるaxe-core、
Lighthouse、リンク用のlychee、Prettier、markdownlint、ESLint、Ruff、
basedpyright、yamllint、ShellCheck、codespell、gitleaksです。Task
が、それぞれの処理を一つのタスク名で実行し、pre-commitは、ファイル単
位の検査を担う半分を、コミットごとに改めて実行します。同じページは、
ゲートの外に置く検査も明記しています。Puppeteerで動くブラウザー検査
のうち、表示領域からのはみ出しと視覚的な差分の二つで、人が必要に応じ
て実行します。

あるポートフォリオのページは、一人のプロジェクトにはレビュアーがまっ
たくいない、という状況から始まります。規則に違反したら、誰かが気付く
のを待つのではなく、コミットを失敗させるため、規則を実行可能にする必
要がありました。記録された2026年8月の実装段階での解決策は、警告とい
う区分を設けない、22本のリンターによるコミットゲートと、既製のツール
では判断できない、プロジェクト固有の検査でした。たとえば、デプロイす
るツリーに非公開のパスやホスト名がないことや、三言語の文章が文体の規
則を守ることです。既にある違反も、受け入れず、その作業の中で直しま
す。ページは、代償を明確に述べています。コミットは遅くなり、このプロ
ジェクトのレビュアーは、ゲートだけです。

ゲートの中で食い違いが起きることもあります。別のページは、コミット
フックと完全なゲートがあり、文書にはフックがゲートを実行すると書かれ
ている一方、二つのファイルで検査の一覧を手作業で管理していたプロジェ
クトを説明します。両方の一覧を、実際に呼び出す検査までたどって比較す
るテストにより、完全なゲートでしか動かない検査が五つ見つかりました。
五つとも、文章を読む検査でした。コードを守る検査はすべて自動実行さ
れ、文章を守る検査は、誰かが思い出したときにしか動いていませんでし
た。五つをフックに移し、そのうち二つを、フックの実行時間に収まる速さ
にしました。一覧の違いを検出するため、比較テストを残しました。

問題が起きるところ

ゲートの失敗の多くは、合格と表示しながら問題を通してしまう形で起きま
す。

合格表示の裏で、警告が積み上がります。
エラーのときだけ失敗するゲートでは、警告が増え続け、やがてログが長す
ぎて読めなくなり、本当の問題が二百一件目の警告として現れます。警告と
いう区分をなくします。不合格にする価値がある規則なら不合格にし、そう
でなければ無効にします。

スキップした検査が、合格として扱われます。
GitHubでは、スキップのステータスでも必須の検査を満たし、`if:`条件に
よってスキップしたジョブも成功を報告します。失敗したジョブに依存する
ジョブもスキップされ、マージを止めない場合があります。GitHubは、
`always()`を`needs`と組み合わせるよう勧めています。常に実行され、必
要とするジョブがすべて成功したときだけ合格するジョブを、一つ必須にし
ます。

```yaml
i# .github/workflows/check.yml（抜粋）		engineer.company	70
jobs:
    gate:
        if: always()
        needs: [lint, test, build]
        runs-on: ubuntu-latest
        steps:
            - run: |
                  for result in ${{ join(needs.*.result, ' ') }}; do
                      test "$result" = success || exit 1
                  done
```

逆の落とし穴もあります。パスやブランチのフィルターによって必須のワー
クフローをスキップすると、検査が保留のままになり、すべてのマージを止
めます。スキップされ得るワークフローを、必須にしないようにします。

二つの一覧が食い違います。
フックが実行する検査とサーバーの検査が違い、文書には一致すると書かれ
ています。検査の定義を一つにして、どの場所からも呼び出すか、一覧を比
較し、違っていたら失敗するテストを維持します。

ゲートが遅くなり、人が迂回します。
フックを省略するフラグはすぐに使えます。また、GitHubのブランチ保護
は、既定ではリポジトリー管理者に適用されません。「Do not
allow bypassing the above
settings」（上記設定の迂回を許可しない）が、それを変えます。どこに時
間がかかるかを測り、独立した検査を並行して実行し、コミット時に動かす
半分を小さく保ち、本当に遅い検査は、文書化した手動の手順へ移します。

何も検査しなかったのに、合格します。
一つのファイルにも一致しないglobや、ディレクトリー全体を除外するパ
ターンを指定されたリンターは、エラーなく終了します。その終了結果は、
問題のないコードを検査した場合と同じに見えます。ゲート自体をテストし
ます。各検査に、間違いがあると分かっているファイルを渡し、確実に不合
格になるかを確認します。

参考資料

  * 品質ゲート入門 — 条件、既定のSonar way、新しいコードを対象とする
考え方です。

  * 保護されたブランチについて — 必須のステータスチェックと、迂回で
きる人です。

  * 必須のステータスチェックのトラブルシューティング — 合格とみなす
ステータスと、スキップしたワークフローやジョブの動作です。

  * 自動マージ — GitLabの「Pipelines must succeed」検査と、スキップ
したパイプラインの扱いです。

  * pre-commit — 一度定義した検査を、コミット時とプッシュ時のGitフッ
クとして組み込む仕組みです。

  * Taskの依存関係 — タスクの依存先を並行して実行し、コマンドを順番
に実行する仕組みです。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/quality-gate/	engineer.company	70
