GitHub Code Quality を使ってみる

1. はじめに

コードレビューで「ここ、nullチェック漏れてますよ」「この変数使われてないですね」といった指摘を何度も繰り返していませんか。GitHub Code Qualityは、こうした機械的にチェック可能な品質問題を自動検出し、修正案まで提示してくれる機能です。

現在パブリックプレビュー中のこの機能について、技術的な詳細と実践的な活用方法を解説します。

2. GitHub Code Qualityとは

GitHub Code Qualityは、リポジトリのコード品質を継続的に監視・改善するための統合ソリューションです。CodeQL による静的解析と、大規模言語モデル（LLM）による動的分析を組み合わせることで、包括的な品質管理を実現します。

2.1 主要な特徴

1. 二段構えの分析アプローチ

   • CodeQL による規則ベースの静的解析
   • LLM による文脈を考慮した動的分析

2. プルリクエスト時の品質ゲート

   • マージ前に品質基準を強制
   • ブロック条件をカスタマイズ可能

3. 自動修正提案（Copilot Autofix）

   • 検出した問題に対する具体的な修正コード
   • Copilot ライセンス不要

4. 包括的な可視化

   • リポジトリ全体の品質評価
   • 信頼性・保守性の定量的指標

3. 対応言語

現在、以下の言語に対応しています。

言語	CodeQL分析	検出クエリ数（目安）
C#	○	60+
Go	○	20+
Java	○	100+
JavaScript/TypeScript	○	100+
Python	○	80+
Ruby	○	3+

AI分析については、これらの言語以外も対象となる可能性があります。

4. アーキテクチャと動作フロー

4.1 全体フロー

4.2 プルリクエスト時の処理

1. トリガー: デフォルトブランチへのプルリクエスト作成・更新
2. 分析: GitHub Actions上でCodeQLが実行（動的ワークフロー「Code Quality」として表示）
3. 結果通知: github-code-quality[bot] がコメントを投稿
4. ステータスチェック: CodeQL - Code Quality / Analyze チェックが表示

4.3 デフォルトブランチでの処理

1. 定期スキャン: デフォルトブランチ全体をCodeQLで分析
2. AI分析: 最近プッシュされた最大5ファイルをLLMで分析
3. ダッシュボード更新: Security タブに結果を反映

5. 品質評価の仕組み

5.1 評価軸

GitHub Code Qualityは、2つの観点からコードを評価します。

5.1.1 Reliability（信頼性）

コードが意図した通りに正確に、予測可能に、一貫して動作するかを評価します。

検出される問題の例:

• パフォーマンス問題
• 並行処理の不具合
• エラーハンドリングの欠陥
• ロジックエラー
• API設計の問題
• アクセシビリティ問題

5.1.2 Maintainability（保守性）

コードの理解しやすさ、変更しやすさ、拡張しやすさを評価します。

検出される問題の例:

• ベストプラクティス違反
• 未使用・デッドコード
• 重複コード
• 過度な複雑性
• 論理的冗長性
• ドキュメント不足
• 依存関係の問題

5.2 重要度レベル

各検出項目には、以下の重要度が割り当てられます。

レベル	定義	例
Error	バグや重大な保守性リスクを引き起こす可能性が高い	null参照、型の不一致、到達不可能なコード
Warning	品質や信頼性に影響する可能性があるが、即座に致命的ではない	未使用変数、潜在的なメモリリーク
Note	軽微な改善提案や推奨事項	コーディングスタイル、最適化の機会

5.3 レーティングシステム

リポジトリ全体の品質は、5段階で評価されます。

レーティング	説明	判定基準
Excellent	ベストプラクティスを実践	品質問題が検出されない
Good	軽微な問題または改善提案あり	Note レベルの問題が1件以上
Fair	中程度の問題あり	Warning レベルの問題が1件以上
Needs Improvement	高重要度の問題あり	Error レベルの問題が1件以上

このレーティングは、Security タブの「Standard findings」ダッシュボードで確認できます。

6. 実践：セットアップから運用まで

6.1 前提条件

1. リポジトリ要件

   • GitHub Team または GitHub Enterprise Cloud の組織所有リポジトリ
   • GitHub Actions が有効

2. 権限要件

   • リポジトリオーナー、組織オーナー、セキュリティマネージャー、または管理者ロール

3. エンタープライズポリシー（該当する場合）

   • Advanced Security ポリシーで Code Quality が許可されている必要があります

6.2 ステップ1: Code Quality の有効化

1. リポジトリの Settings タブを開く
2. サイドバーの Security セクションから Code quality を選択
3. Enable code quality ボタンをクリック
4. 設定を確認：
   • Languages: 分析対象言語を選択（不要な言語はチェックを外す）
   • Runner type: デフォルトは GitHub ホストランナー、必要に応じてラベル付きランナーを指定
5. Save changes をクリック

6.3 ステップ2: 品質ゲートの設定（オプション）

プルリクエストでの品質基準を強制する場合、ruleset を設定します。

# ruleset の設定例（概念図）
ruleset:
  name: "コード品質基準"
  enforcement: Active
  target_branches:
    - default
  rules:
    - require_code_quality_results:
        severity: "Warnings and higher"  # Warning 以上をブロック

設定手順:

1. Settings > Rules > Rulesets を開く
2. New branch ruleset をクリック（または既存のものを編集）
3. ruleset を設定：
   • 名前を定義
   • Enforcement status を「Active」に設定
   • Target branches に「Include default branch」を追加
4. Branch rules で「Require code quality results」を有効化
5. Severity を選択：
   • Errors: Error レベルをブロック
   • Warnings and higher: Warning 以上をブロック
   • Notes and higher: Note 以上をブロック
   • All: すべての問題をブロック
6. Create または Save changes をクリック

6.4 ステップ3: 初回スキャンの確認

有効化後、以下が自動的に実行されます。

1. プルリクエストスキャン: 新規・更新されたPRに対して
2. デフォルトブランチスキャン: リポジトリ全体（数分かかる場合あり）
3. AI分析: 最近プッシュされたファイル

結果は以下で確認できます。

• プルリクエスト: Checks セクションと bot コメント
• Security タブ: Code quality > Standard findings（CodeQL結果）
• Security タブ: Code quality > AI findings（LLM結果）

7. 日常的な運用フロー

7.1 プルリクエストでの活用

7.1.1 問題の確認と優先順位付け

• PRの Checks セクションで CodeQL - Code Quality / Analyze の状態を確認
• github-code-quality[bot] のコメントを確認
• Error レベルから優先的に対応
• 品質ゲートで設定した重要度レベル以上は必須対応

7.1.2 修正方法の選択

方法A: Copilot Autofix を使用（Copilot ライセンス不要）

botコメント内の修正案を確認し、「Commit suggestion」をクリックすると自動でコミットされ、再スキャンが実行されます。

方法B: Copilot coding agent に委譲（Copilot ライセンス必要）

PRにコメント「@Copilot この品質問題を修正してください」と記載すると、Copilotが👀で反応しセッションを開始、修正PRを作成します。

方法C: Dismiss（却下）

却下する正当な理由：

• レガシーコードでメンテナンス対象外
• チームの規約で許容されている例外
• False positive（誤検出）

7.1.3 マージ前の最終確認

• すべての必須問題が解決済みか
• Checks セクションで緑のチェックマークを確認

7.2 デフォルトブランチでの品質管理

7.2.1 Standard findings での作業フロー

1. 全体像の把握: Reliability と Maintainability のレーティングを確認
2. 優先順位の決定: フィルターで Error レベルに絞り込み、検出件数が多いルールから着手
3. 詳細調査: ルール名をクリックして該当箇所を表示、「Show more」で説明・推奨修正・コード例を確認
4. 修正の実施: 「Generate fix」で修正案を確認し PR 作成。複数の問題をまとめて修正する場合は同じブランチにコミット
5. 進捗の追跡: マージ後、数分待ってレーティングの変化と残りの問題件数を確認

7.2.2 AI findings での作業フロー

1. 最近の変更を確認: 最大5ファイルのAI分析結果とプッシュ日時を確認
2. 問題の評価: ファイル名をクリックして詳細を表示し、提案内容が妥当かを判断
3. 修正の委譲または実施: 複数ファイルは「Assign selected to Copilot」、単一ファイルは「Assign to Copilot」または「Open pull request」
4. 進捗確認: Copilot が作成したPRを確認、エージェントページでセッションログを追跡

8. 検出ルールの詳細

各言語で検出される具体的な問題を見ていきます。

8.1 Python の例

Maintainability 関連:

• 'import *' may pollute namespace: 名前空間の汚染
• Commented-out code: コメントアウトされたコード
• Duplicate key in dict literal: 辞書の重複キー
• First parameter of a method is not named 'self': メソッドの第一引数が self でない
• Module is imported more than once: モジュールの重複インポート
• Should use a 'with' statement: with 文を使うべき箇所
• Unreachable code: 到達不可能なコード
• Unused import: 未使用のインポート

Reliability 関連:

• __init__ method returns a value: init が値を返している
• Comparison using is when operands support __eq__: == を使うべきところで is を使用
• File is not always closed: ファイルが必ずクローズされない
• Illegal raise: 不正な例外送出
• Missing call to superclass __init__ during object initialization: スーパークラスの init 呼び出し漏れ
• Non-callable called: 呼び出し不可能なオブジェクトの呼び出し
• Wrong number of arguments in a call: 引数の数が間違っている

8.2 JavaScript の例

Maintainability 関連:

• Duplicate property: プロパティの重複
• Expression has no effect: 効果のない式
• Misleading indentation after control statement: 誤解を招くインデント
• Semicolon insertion: セミコロン自動挿入の問題
• Unused variable, import, function or class: 未使用の変数・インポート・関数・クラス
• Useless assignment to local variable: 無駄なローカル変数への代入

Reliability 関連:

• Assignment to constant: 定数への代入
• Comparison with NaN: NaN との比較
• Duplicate parameter names: 重複したパラメータ名
• Illegal invocation: 不正な呼び出し
• Loop iteration skipped due to shifting: シフトによるループイテレーションのスキップ
• Missing await: await の欠落
• Property access on null or undefined: null/undefined のプロパティアクセス
• Unbound event handler receiver: バインドされていないイベントハンドラ

8.3 Java の例

Maintainability 関連:

• Boxed variable is never null: ボックス化された変数が null になることはない
• Class has same name as super class: スーパークラスと同じクラス名
• Inefficient empty string test: 非効率な空文字列テスト
• Inner class could be static: static にできる内部クラス
• Missing Override annotation: Override アノテーションの欠落
• Unread local variable: 読み込まれないローカル変数
• Unused classes and interfaces: 未使用のクラス・インターフェース

Reliability 関連:

• Array index out of bounds: 配列の範囲外アクセス
• Dereferenced variable may be null: null の可能性がある変数の参照
• Double-checked locking is not thread-safe: ダブルチェックロッキングはスレッドセーフでない
• Equals on incomparable types: 比較不可能な型の equals
• Inconsistent equals and hashCode: equals と hashCode の不整合
• Reference equality test of boxed types: ボックス化型の参照等価テスト
• Unreachable catch clause: 到達不可能な catch 句

8.4 その他の言語

C#、Go、Ruby、TypeScript についても同様のパターンで、各言語特有の問題が検出されます。全言語で合計200以上のルールが用意されており、詳細は GitHub Docs で確認できます。

9. Copilot Autofix の仕組み

Copilot Autofix は、検出された問題に対して自動的に修正案を生成する機能です。

9.1 動作原理

1. コンテキストの収集

   • 検出されたコードの問題
   • 周辺のコード
   • リポジトリの構造
   • ベストプラクティス情報

2. プロンプトの生成

   • 収集した情報を LLM 向けのプロンプトに整形

3. LLM による分析と生成

   • Copilot の言語モデルがプロンプトを分析
   • 修正案を生成

4. フォーマットと提示

   • 修正案を具体的なコード変更として提示
   • ワンクリックで適用可能な形式

9.2 重要な注意点

必ずレビューが必要です:

• Autofix は 100% 成功するわけではない
• ロジック、セキュリティ、スタイルの観点で確認
• 必要に応じて修正を編集してから適用

制限事項:

• すべての問題に対して修正案が生成されるわけではない
• ベストエフォートベース
• False positive の可能性

Copilot ライセンスは不要:

• Autofix の適用自体には Copilot ライセンス不要
• Copilot coding agent への委譲には Copilot ライセンスが必要

10. LLM による AI 分析の特徴

10.1 CodeQL 分析との違い

観点	CodeQL 分析	LLM AI 分析
アプローチ	ルールベース	コンテキスト理解
対象範囲	全体 + PR	最近変更された最大5ファイル
対応言語	7言語に限定	制限なし（可能性）
実行タイミング	PR時 + 定期	デフォルトブランチへのプッシュ後
結果表示	Standard findings	AI findings
強み	網羅的、再現性高い	文脈的、柔軟

10.2 AI 分析の利点

1. 文脈的な洞察

   • ルールに縛られない柔軟な分析
   • コードの意図を理解した提案

2. 言語の制約が少ない

   • CodeQL が対応していない言語でも分析可能性

3. 技術的負債の早期発見

   • 最近変更されたファイルに焦点
   • アクティブに開発中のコードを優先

10.3 責任ある使用

AI 分析には以下の制限があることを認識してください。

制限事項:

• 不完全な検出: すべての問題を検出できるわけではない
• False positive: 誤検出の可能性
• 精度のばらつき: 提案の質にばらつきがある
• バイアスの可能性: 学習データのバイアスが反映される可能性

推奨事項:

• AI 分析の結果は必ず人間が検証
• CodeQL 分析と組み合わせて使用
• チームの規約と照らし合わせて評価
• フィードバックボタン（👍👎）を活用して品質改善に協力

11. コストと制限

11.1 料金

パブリックプレビュー期間中:

• Code Quality 自体は無料
• GitHub Actions の実行時間のみ消費

将来的には:

• GitHub Team または GitHub Enterprise Cloud プランで利用可能
• 詳細な料金体系は正式リリース時に発表予定

11.2 技術的制限

1. 言語サポート

   • CodeQL 分析: 7言語のみ
   • AI 分析: より広範だが、品質保証の対象は主要言語

2. スキャン範囲

   • AI 分析: 最大5ファイルまで

3. 実行環境

   • GitHub Actions が必要
   • ランナーのリソースを消費

4. アクセス制限

   • 組織所有リポジトリのみ
   • エンタープライズポリシーの影響を受ける

12. トラブルシューティング

12.1 よくある問題と対処法

12.1.1 問題1: Code Quality が有効化できない

原因と対処:

• エンタープライズポリシーで制限されている
  → エンタープライズオーナーに Advanced Security ポリシーの確認を依頼
• GitHub Actions が無効
  → Settings > Actions > General で Actions を有効化

12.1.2 問題2: スキャンが失敗する

原因と対処:

• Actions の実行時間制限に達した
  → 実行時間の予算を確認、必要に応じて増やす
• ランナーのリソース不足
  → ラベル付き自己ホストランナーの使用を検討
• ワークフローの設定ミス
  → Actions タブでログを確認（「Viewing logs to diagnose failures」参照）

12.1.3 問題3: 品質ゲートが意図せずブロック

原因と対処:

• ruleset の severity 設定が厳しすぎる
  → ruleset を編集して緩和
• Legacy コードで大量のエラー
  → 段階的に severity を緩めて移行期間を設ける

12.1.4 問題4: False positive が多い

原因と対処:

• ルールがプロジェクトに適さない
  → 該当の問題を Dismiss し、理由を記録
  → GitHub にフィードバックを送信（👎ボタン）

12.1.5 問題5: AI findings が表示されない

原因と対処:

• リポジトリが非アクティブ
  → プッシュしてスキャンをトリガー
• 最近変更されたファイルに問題がない
  → 正常動作、Standard findings を確認

12.2 ログの確認方法

13. 実際の導入事例シナリオ

13.1 シナリオ1: レガシーコードベースの段階的改善

状況: 大規模な既存コードベースで技術的負債が蓄積し、Error レベルの問題が数百件存在

アプローチ:

初期フェーズ（1〜2週間）: Code Quality を有効化（品質ゲートは未設定）し、Standard findings で全体像を把握。Error レベルの問題をカテゴリ別に整理。

クイックウィンフェーズ（2〜4週間）: 自動修正可能な「Unused variable」「Unused import」などの低リスク問題から着手。Autofix を活用して迅速に対応。

高影響問題の修正フェーズ（4〜8週間）: Null 参照、型の不一致などの高リスク問題をチーム全体で分担。Error レベルを 50% 削減を目標に設定。

品質ゲート導入フェーズ: Severity を「Errors」に設定し、新規コードで Error レベルをブロック開始。

継続的改善: 定期的に Severity を厳しく調整し、最終的に「Notes and higher」を目指す。

13.2 シナリオ2: 新規プロジェクトでの品質維持

状況: これから開発開始するプロジェクトで、最初から高品質を維持したい

アプローチ:

初期設定: Code Quality を有効化し、品質ゲートを「All」に設定（最も厳しい基準）。

開発中: すべてのPRで Autofix を積極活用。False positive は即座に Dismiss して記録し、チームで品質基準を議論・合意形成。

定期見直し: Dismiss 理由を分析し、必要に応じて Severity を調整。チームのコーディング規約を更新。

13.3 シナリオ3: 複数チームでの運用

状況: 10以上のチームが同じリポジトリで作業し、品質基準が統一されていない

アプローチ:

準備フェーズ: 各チームのリードが集まって品質基準を議論し、ruleset で組織全体の基準を定義。ドキュメント化とトレーニングを実施。

パイロット運用: 1〜2チームで先行導入し、フィードバックを収集して ruleset を調整。

全体展開: すべてのチームで有効化し、定期的にメトリクスをレビュー。ベストプラクティスを共有。

継続的改善: 品質レポートを作成してレーティングの推移を追跡し、チーム間で知見を共有。

14. まとめ

GitHub Code Quality は、コード品質管理のアプローチを根本から変える可能性を持つ機能です。

14.1 主な利点

1. 自動化による効率化

   • 機械的なレビュー指摘を削減
   • 人間はより高度な設計レビューに集中

2. 継続的な品質可視化

   • リポジトリの健全性を定量的に把握
   • ステークホルダーへの報告が容易

3. 早期発見・早期修正

   • マージ前に問題をキャッチ
   • 技術的負債の蓄積を防止

4. 学習機会の提供

   • Autofix の提案から学べる
   • ベストプラクティスの周知

14.2 成功のポイント

1. 段階的な導入

   • いきなり厳しい基準を設けない
   • チームの状況に応じて調整

2. チームでの合意形成

   • 品質基準をチーム全体で議論
   • False positive の扱いを明確化

3. 継続的な改善

   • メトリクスを定期的にレビュー
   • フィードバックを GitHub に送信

4. 現実的な目標設定

   • 完璧を求めすぎない
   • 改善の進捗を評価

14.3 今後の展望

パブリックプレビュー期間中は、機能が変更される可能性があります。定期的に GitHub Docs をチェックし、最新の情報を確認してください。

---

免責事項: この記事は、GitHub Docs の公開情報に基づいています。パブリックプレビュー中のため、仕様は変更される可能性があります。最新の情報は公式ドキュメントでご確認ください。