GitHub Code Qualityの検出結果をプルリクエストのマージ必須条件にしたい場合、最初からrulesetをActiveにするのは避けるべきです。現在のPRがどの程度違反するか分からない状態で強制すると、品質問題だけでなく解析の失敗や設定不備によっても開発が止まる可能性があります。
このケースには、GitHubが公式の解決策として用意しているEvaluateモードがあります。まず「Activeならブロックされていた操作」を観測し、Code Qualityのしきい値を調整してからActiveへ切り替えるのが安全です。GitHub Code Qualityは2026年7月20日にGitHub Enterprise CloudとGitHub Teamで一般提供され、段階導入のためのEvaluateモードを備えた品質ゲートも追加されました。 (The GitHub Blog)
実務では、既存のブランチ保護を維持したまま、Code Quality専用のrulesetを別に作成してEvaluateモードで運用する方法が適しています。本記事では、しきい値の選び方、設定手順、Rule Insightsで確認すべき項目、Activeへ切り替える判断基準まで解説します。
GitHub Code Quality RulesetsはEvaluateモードから始める
GitHubのrulesetには、次の3つのEnforcement statusがあります。
| ステータス | ルールの評価 | PRやpushのブロック | 主な用途 |
|---|---|---|---|
Active | する | する | 本番運用 |
Evaluate | する | しない | 影響調査、しきい値調整 |
Disabled | しない | しない | 一時停止、設定保存 |
Evaluateではルール違反を強制せず、Rule Insightsで「Activeだった場合に成功したか、失敗したか」を確認できます。Disabledとは異なり評価結果が残るため、品質ゲートの試験運用に向いています。 (GitHub Docs)
安全な導入順序は次のとおりです。
- Code Qualityの解析が正常に実行されていることを確認する
- Code Quality専用のbranch rulesetを作る
- Enforcement statusを
Evaluateにする - しきい値を設定する
- 通常のPRを一定期間観測する
- Rule Insightsで失敗理由を分類する
- しきい値や対象リポジトリを調整する
- 問題がなければ
Activeに切り替える
Evaluateモードは単なるテスト設定ではありません。品質基準そのものが妥当か、解析基盤が安定しているか、開発チームが指摘を解消できるかを分けて確認する期間と考えるのが適切です。
対象プランと設定前の前提条件
Code Qualityのしきい値をrulesetで設定できる対象は、GitHub TeamまたはGitHub Enterprise Cloudです。GitHub Enterprise Serverは、2026年7月20日の一般提供開始時点では対象外です。リポジトリ所有者、Organization所有者、または管理権限を持つユーザーが設定します。 (The GitHub Blog)
設定前に、次の条件を確認してください。
- 対象リポジトリでGitHub Code Qualityが有効になっている
- Code Qualityが対応する言語のコードが含まれている
- 最近のPRで
CodeQL - Code Qualityチェックが正常終了している - 対象ブランチと対象リポジトリが明確になっている
- 既存のrepository rulesetとorganization rulesetを把握している
- GitHub Actionsの実行環境や利用枠が安定している
特に重要なのが、CodeQL - Code Qualityチェックの確認です。解析が正常に動いていない状態でActiveにすると、品質上の違反がなくてもPRをマージできなくなる可能性があります。GitHub公式ドキュメントも、rulesetを追加する前に最近のPRを開き、Checks欄でCodeQL - Code Qualityが正常に結果を返していることを確認するよう案内しています。 (GitHub Docs)
rulesetのしきい値は2種類を区別する
GitHub Code Quality Rulesetsでは、主に次の2種類の基準を扱います。
- Code Quality findingsの重大度
- コードカバレッジ
これらは同じ設定項目ではありません。それぞれ別のbranch ruleとして設定します。
Code Quality findingsの重大度しきい値
Code Qualityの検出結果をPRの必須条件にするには、Require code quality resultsを使用します。
Severityでは、マージ前に解決を要求する最低重大度を選択します。
| Severity | ブロック対象 | 導入時の使い分け |
|---|---|---|
Errors | Errorの未解決結果 | 既存リポジトリで最初に試しやすい |
Warnings and higher | WarningとError | 重大な警告も新規混入させたくない場合 |
Notes and higher | Note、Warning、Error | 指摘対応が定着した成熟リポジトリ向け |
All | すべての未解決結果 | 十分なEvaluate期間を経た厳格運用向け |
Severityは、どの重大度以上の結果を解決しなければマージできないかを指定する設定です。例えばWarnings and higherを選ぶと、WarningまたはErrorの未解決結果があるPRをActiveモードでブロックします。 (GitHub Docs)
既存コードの品質状況が分からない場合は、EvaluateモードでErrorsまたはWarnings and higherから始めるのが現実的です。最初からAllにすると、軽微な指摘まで一律に対応が必要となり、品質改善よりもルール回避が優先される運用になりかねません。
AIによる検出結果はしきい値の対象にできない
GitHub Code Qualityには、CodeQLによる決定論的な解析とAI支援による検出があります。ただし、Code QualityのAI findingsはrulesetのしきい値対象には設定できません。PRのマージゲートに利用できるものと、レビュー支援として表示されるものを混同しないようにしてください。 (GitHub Docs)
そのため、Evaluate期間中は次の2つを分けて評価します。
- rulesetでブロック候補となるCodeQL findings
- 開発者への改善提案として扱うAI findings
「Code Qualityに表示された指摘がすべてマージ必須条件になる」と考えると、実際の挙動との食い違いが生じます。
コードカバレッジは別のルールで設定する
コードカバレッジを必須条件にする場合は、Require code quality resultsではなく、別のRestrict code coverageルールを使います。
設定できるしきい値は次の2つです。
| 項目 | ブロックされる条件 |
|---|---|
Minimum coverage percentage | PRブランチの集計カバレッジが指定値を下回る |
Maximum coverage drop | デフォルトブランチより指定したポイント数を超えて低下する |
例えば、次の設定を考えます。
- Minimum coverage percentage：70%
- Maximum coverage drop：2ポイント
- デフォルトブランチ：78%
- PRブランチ：74%
このPRは最低カバレッジ70%を満たしていますが、デフォルトブランチから4ポイント低下しているため、Maximum coverage dropの条件には違反します。
値を0にすると、そのカバレッジしきい値は無効になります。なお、コードカバレッジのruleset機能は公式ドキュメント上でPublic Previewとされており、利用前にカバレッジデータのアップロード設定が必要です。 (GitHub Docs)
既存rulesetとは分けて作成する
Evaluateモードで安全に試す場合は、Code Quality専用のrulesetを新しく作成する方法が適しています。
例えば、すでに次のルールを含むActiveなrulesetがあるとします。
- PR経由の変更を必須化
- 2人の承認を要求
- force pushを禁止
- required status checksを要求
このrulesetにCode Qualityを追加した後、ruleset全体をEvaluateへ変更すると、Code Qualityだけでなく、既存のレビュー要件やブランチ保護も強制されなくなります。
そのため、次のように分けます。
| ruleset名の例 | ステータス | 含めるルール |
|---|---|---|
default-branch-protection | Active | レビュー、status checks、force push禁止 |
code-quality-default | Evaluate | Require code quality results |
Code Qualityの検証が終わったら、code-quality-defaultだけをActiveに変更します。これにより、既存のブランチ保護を弱めずに段階導入できます。
複数のrulesetがある場合は最も厳しい条件が適用される
GitHubのrulesetには優先順位がありません。同じブランチに複数のrulesetやbranch protection ruleが適用される場合、ルールは集約され、同じルールが異なる条件で設定されていれば、より厳しい条件が有効になります。 (GitHub Docs)
例えば、次の状態ではEvaluateモードが期待どおりに機能しません。
- repository ruleset：
Warnings and higher、Evaluate - organization ruleset：
Notes and higher、Active
この場合、organization rulesetのActiveな条件が引き続き適用されます。repository rulesetをEvaluateにしても、上位のActiveなルールを上書きしたり緩和したりはできません。
設定前に、少なくとも次の範囲を確認してください。
- リポジトリ単位のruleset
- Organization単位のruleset
- 従来のbranch protection rule
- 対象ブランチのInclude、Exclude条件
- Bypass listの設定
「EvaluateにしたのにPRがブロックされる」という場合は、別のActiveなrulesetが適用されていないかを確認します。
リポジトリ単位でEvaluateモードを設定する手順
最近のPRでCode Qualityの動作を確認する
対象リポジトリの最近のPRを開きます。
PR画面下部のChecksで、次のチェックを確認してください。
CodeQL - Code Quality確認するポイントは次のとおりです。
- チェックが実行されている
- 長時間Pendingのままになっていない
- 成功または解析結果が返っている
- 対象言語が正しく解析されている
- GitHub Actions側で恒常的なエラーが発生していない
チェック自体が表示されない場合は、rulesetを作る前にCode Qualityの有効化状態や対応言語、workflowの動作を確認します。
Code Quality専用のbranch rulesetを作成する
対象リポジトリで、次の順に開きます。
Settings
→ Rules
→ Rulesets
→ New ruleset
→ New branch ruleset既存rulesetの編集ではなく、新しいbranch rulesetを作るのが安全です。
Ruleset nameには、役割が分かる名前を付けます。
code-quality-defaultOrganization単位のパイロットなら、次のような名前でもよいでしょう。
code-quality-pilotEnforcement statusをEvaluateにする
Enforcement statusでEvaluateを選択します。
ここでActiveを選ぶと、保存直後から条件に違反するPRのマージがブロックされます。現在の違反量や解析の安定性が分からない段階では、Evaluateを選んでください。
対象ブランチを指定する
Target branchesで対象を追加します。
最初の導入では、次を選択します。
Include default branch全ブランチを対象にすると、開発用ブランチやリリースブランチまで意図せず評価対象になる可能性があります。まずデフォルトブランチへのPRだけで試し、必要性が確認できてから対象を広げる方が管理しやすくなります。
Require code quality resultsを有効にする
Branch rulesで次のルールを有効にします。
Require code quality resultsCode Qualityは専用のルールとして提供されています。一般的なRequire status checks to pass before mergingへチェック名を手入力する方法と混同しないでください。
このルールをActiveにすると、次の状態でPRのマージがブロックされます。
- Code Qualityの解析が進行中
- 解析が失敗した
- 設定した重大度以上のCode Quality resultが検出された
解析失敗には、GitHub Actionsの利用枠を使い切った場合なども含まれます。品質違反がなくても解析基盤の問題で止まる可能性があるため、Evaluate期間中に失敗原因を確認する必要があります。 (GitHub Docs)
Severityを選択する
初回設定では、リポジトリの状態に応じて次を選びます。
| リポジトリの状態 | 初回候補 |
|---|---|
| 既存コードが多く、指摘量が不明 | Errors |
| PRレビューや静的解析がすでに定着 | Warnings and higher |
| 新規リポジトリで品質ルールを統一済み | Notes and higherも検討 |
| すべての指摘を必ず解決できる体制 | All |
迷う場合は、Warnings and higherをEvaluateで試し、違反が多すぎる場合にErrorsへ緩和する方法が分かりやすいでしょう。
rulesetを保存する
設定内容を確認し、Createをクリックします。既存rulesetを編集している場合はSave changesです。
保存後、通常の開発フローで新しいPRを作成するか、既存PRへ更新コミットを追加し、評価結果が蓄積される状態にします。
Organization単位でパイロット導入する手順
複数リポジトリへ同じ基準を適用する場合は、Organization単位のrulesetを利用できます。ただし、最初から全リポジトリを対象にせず、通常のPRが継続的に発生している一部のチームやリポジトリを選ぶ方が安全です。
パイロット対象は、次のいずれかで管理します。
Selected repositoriesで明示的に選択する- カスタムプロパティなどを利用し、条件に一致するリポジトリを対象にする
GitHub公式の大規模展開手順でも、単一の開発チームや関連アプリケーション群から始め、Evaluateモードで影響を確認してから対象を広げる方法が案内されています。 (GitHub Docs)
Organization設定では、次の順にruleset画面を開きます。
Organization
→ Settings
→ Repository
→ Rulesetsその後は、リポジトリ単位と同様にbranch rulesetを作成し、次を設定します。
- Enforcement status：
Evaluate - Target repositories：パイロット対象
- Target branches：デフォルトブランチ
- Branch rules：
Require code quality results - Severity：初期しきい値
リポジトリごとに品質状況が大きく異なる場合は、全社共通のrulesetを1つ作るより、成熟度別にrulesetを分けた方が運用しやすくなります。
Rule Insightsで確認する項目
Evaluateモードを設定しただけでは、適切なしきい値は決まりません。Rule Insightsを使い、どのPRがどの理由で失敗判定になったかを確認します。
Organizationでは、次の順に開きます。
Organization
→ Settings
→ Repository
→ Rule insightsRule Insightsでは、ruleset、リポジトリ、実行者、期間などで絞り込みができます。Evaluateモードのイベントには、Activeだった場合にPassまたはFailになっていた結果が表示されます。個別イベントを展開すると、どのルールが失敗したかも確認できます。 (GitHub Docs)
Rule InsightsとHistoryを混同しない
rulesetには、似た名前の確認機能があります。
| 機能 | 確認できる内容 |
|---|---|
| Rule Insights | PRやpushがルールにPass、Fail、Bypassした結果 |
| History | rulesetの設定変更履歴 |
しきい値の妥当性を判断する場合に見るのはRule Insightsです。Historyは、誰がいつSeverityや対象リポジトリを変更したかを追跡するときに使います。
失敗理由を品質と解析基盤に分ける
EvaluateでFailになったイベントは、少なくとも次の2種類に分けて集計します。
品質違反率
= Code Quality findingが原因のFail数 ÷ 評価対象PR数
解析基盤失敗率
= 解析失敗や未完了が原因のFail数 ÷ 評価対象PR数この2つを合算して「違反が多い」と判断すると、Severityを誤って緩める可能性があります。
例えば、Failの大半がGitHub Actionsの失敗であれば、しきい値ではなくworkflowや実行枠を直すべきです。一方、正常に解析されたPRの多くがWarningで失敗しているなら、コードベースが現在のしきい値に対応できるかを検討します。
観測結果ごとの対応
| Evaluateで確認した状態 | 考えられる原因 | 次の対応 |
|---|---|---|
| Errorだけが少数発生 | 重大な品質問題を適切に検出 | ErrorsでActiveを検討 |
| Warningで大量にFail | 基準が現在の開発状況より厳しい | Errorsへ緩和するかWarning対応を先行 |
| 解析失敗が繰り返される | Actions、workflow、権限、利用枠の問題 | Active化せず解析基盤を修正 |
| 特定リポジトリだけFailが多い | コードの成熟度や構成が異なる | 対象rulesetを分割 |
| ほとんどFailしない | 基準が緩い、または対象コードが少ない | Warnings and higherなどを再評価 |
| 原因を説明できないFailがある | ルールの重複や対象条件の誤り | 他のrulesetとbranch protectionを確認 |
Evaluate期間は通常の開発サイクルを含める
GitHub公式の大規模展開ガイドでは、判断に必要なPR活動が集まるまで、通常は1〜2週間程度Evaluateモードに置く方法が示されています。 (GitHub Docs)
ただし、PR数が少ないリポジトリでは、日数だけで区切ると十分な評価ができません。次のような変更が含まれるまで観測を続けます。
- 通常の機能追加
- バグ修正
- リファクタリング
- 依存関係の更新
- 自動生成されたPR
- 緊急修正
- 複数言語にまたがる変更
普段は小規模なPRしかないのに、Evaluate期間中にREADMEの更新しか発生しなかった場合、その結果だけでActiveにするのは危険です。日数ではなく、本番運用を代表するPRが含まれているかを判断基準にします。
既存の違反状況とPRへの影響は別に確認する
Evaluateモードで分かるのは、rulesetがActiveだった場合にPRや操作がどう評価されたかです。現在のデフォルトブランチに蓄積している品質上の課題をすべて表すものではありません。
確認対象を次のように分けると判断しやすくなります。
| 確認したい内容 | 使用する画面 |
|---|---|
| 既存コードの保守性、信頼性、蓄積済みfindings | Code Qualityのリポジトリ・Organizationダッシュボード |
| 今後のPRが何件ブロックされるか | EvaluateモードのRule Insights |
| ruleset設定を誰が変更したか | Ruleset History |
| 個別PRで修正すべき内容 | PR上のCode Quality結果 |
一般提供時には、複数リポジトリのmaintainabilityとreliabilityを確認するOrganizationレベルのダッシュボードも追加されています。既存の品質負債と、今後追加される変更へのゲートを分けて管理することが重要です。 (The GitHub Blog)
Activeへ切り替える判断基準
次の条件を満たしたら、Activeへの切り替えを検討します。
CodeQL - Code Qualityが継続して正常終了している- 代表的な種類のPRをEvaluateで確認した
- FailになったPRの理由を説明できる
- 解析基盤によるFailが解消されている
- 選択したSeverityを開発チームが理解している
- 指摘の修正、却下、例外判断の担当者が明確である
- 他のrulesetとの重複を確認した
- 緊急時のBypass運用を必要に応じて決めた
単に「Fail件数が少ない」だけでは不十分です。Failが少なくても、発生した1件を誰も修正できない、または誤検出時の判断者がいない状態では運用が止まります。
反対に、Failが一定数あっても、すべて妥当な指摘で短時間に修正できているなら、Active化する価値があります。
EvaluateからActiveへ切り替える手順
対象rulesetを開きます。
Settings
→ Rules
→ Rulesets
→ code-quality-defaultOrganization rulesetの場合は次の場所です。
Organization
→ Settings
→ Repository
→ Rulesets
→ code-quality-defaultEnforcement statusを次のように変更します。
Evaluate
→ ActiveSeverity、対象ブランチ、対象リポジトリを再確認し、Save changesをクリックします。
Activeへ変更すると、設定した重大度以上の未解決結果がある場合だけでなく、解析が進行中または失敗している場合もマージがブロックされます。 (GitHub Docs)
切り替え後は、次の2種類のPRで動作を確認します。
- Code Qualityの問題がない通常のPR
- 設定したSeverity以上の既知の問題を含む検証用PR
1つ目が正常にマージ可能で、2つ目が意図どおりブロックされれば、品質ゲートは期待どおりに動いています。
Active化後に開発が止まった場合の戻し方
想定外のブロックが続く場合は、rulesetを削除するのではなく、Evaluateへ戻します。
Active
→ EvaluateEvaluateへ戻せば強制を解除しつつ、引き続き評価結果を収集できます。Disabledへ変更すると評価自体が停止するため、原因分析を続けたい場合にはEvaluateが適しています。
切り戻した後は、次の順序で原因を確認します。
- Rule InsightsでFailしたルールを確認する
- Code Quality findingと解析失敗を分ける
- Organization側のActiveなrulesetを確認する
- Severityを一段階緩和して再評価する
- 特定リポジトリだけ問題がある場合は対象を分割する
- 解消後に再度Activeへ切り替える
よくある設定ミス
最初からActiveにする
現在の検出量を把握せず、Warnings and higherやAllをActiveにすると、多数のPRが同時に停止する可能性があります。
まずEvaluateで観測し、正常なPRと違反PRの両方を確認します。
既存のActiveなruleset全体をEvaluateにする
Code Qualityだけを試す目的で既存rulesetのステータスをEvaluateへ変更すると、レビュー必須やforce push禁止など、同じruleset内の他の保護も強制されなくなります。
Code Quality専用rulesetを分けて作成してください。
Code scanningとCode Qualityを混同する
Require code scanning resultsはセキュリティ上のcode scanning alertを扱うルールです。Code Qualityの保守性・信頼性に関する結果を必須化する場合は、Require code quality resultsを使います。
AI findingsもマージをブロックすると考える
Code QualityのAI findingsは、rulesetのしきい値対象にはできません。Severity設定によるゲートと、AIによる改善提案は分けて運用します。
カバレッジを同じSeverityで制御しようとする
コードカバレッジはRestrict code coverageで設定します。Require code quality resultsのSeverityを変更しても、カバレッジ基準は変わりません。
解析失敗をコード品質違反として扱う
ActiveなCode Quality rulesetでは、解析失敗もマージを妨げます。Actionsの実行枠、workflow、runner、権限などの問題をSeverity変更で解決しようとしないでください。
repository rulesetだけを確認する
Organization側により厳しいActive rulesetがある場合、repository側のEvaluate設定では強制を解除できません。適用されるrulesetを階層横断で確認します。
段階導入の実践例
複数チームへ展開する場合は、次のような段階に分けると安全です。
| 段階 | 対象 | ステータス | Severity |
|---|---|---|---|
| パイロット観測 | 2〜3個の活発なリポジトリ | Evaluate | Warnings and higher |
| 初回強制 | パイロット対象 | Active | Errorsまたは調整後の基準 |
| 対象拡大 | 同じ技術構成のリポジトリ | Evaluate | パイロットで確定した基準 |
| 標準化 | 安定運用できた対象 | Active | Organization標準 |
| 厳格化 | 成熟リポジトリ | Evaluate後にActive | Notes and higherまたはAll |
すべてのリポジトリへ同じ日に同じ基準を適用する必要はありません。レガシーシステム、新規サービス、自動生成コードを多く含むリポジトリでは、適切なSeverityが異なる場合があります。
共通の最終基準を持ちつつ、移行期間だけrulesetを分ける方が、開発を止めずに標準化を進められます。
まず実施すべき設定
GitHub Code QualityをPRの必須条件にする場合は、次の順序で進めてください。
- 最近のPRで
CodeQL - Code Qualityが正常終了しているか確認する - 既存のブランチ保護とは別にCode Quality専用rulesetを作る
- Enforcement statusを
Evaluateにする - デフォルトブランチを対象にする
Require code quality resultsを有効にするErrorsまたはWarnings and higherから観測を始める- Rule Insightsで品質違反と解析失敗を分けて確認する
- 通常の開発を代表するPRが集まるまで観測する
- しきい値と対象リポジトリを調整する
- 条件が安定したら
Activeへ切り替える
Evaluateモードは、品質ゲートを弱めるための設定ではありません。実際の開発データを使って、止めるべきPRだけを止める基準へ調整するための導入工程です。最初から厳しいルールを強制するのではなく、観測、調整、強制の順に進めることで、開発速度を維持しながらCode QualityをPRの必須条件として定着させられます。
コメント