はじめに
このチュートリアルでは、最初のコメントからマージまで、 Code Qualityの分析を通じて 1 つのプル要求に従います。 学習内容:
- プル リクエストの Code Quality コメントを読み、2 種類の指摘を見分ける方法。
- 検出事項の重大度ラベルを使用して、何を修正し、何を却下し、どの順序で対応するかを決定する方法。
- プル要求で行った選択によって、リポジトリのスコア、バックログ、マージ ゲートがどのように形成されるか。
最後に、サンプルの pull request でブロックされたすべての検出を解決し、クリーンな Code Quality チェックでマージし、各選択を行った 理由 を理解できます。
これはガイド付きチュートリアルであるため、速度よりも理解が優先されます。 自動修正をコミットする方法や検出結果を却下する方法の基本的な手順については、関連するハウツー pull request でのコード品質の結果の修正 を参照してください。
開始する前に
- Code Quality は、投稿するリポジトリで有効になっています。 「GitHub Code Quality の有効化」を参照してください。
- リポジトリでは、ルールベースの結果とスコアが生成されるように、 CodeQL でサポートされている言語が使用されます。 サポートされている言語の一覧については、 GitHub のコード品質 を参照してください。
- 既定のブランチに対してオープン中のプル リクエストがあり、トリアージが必要な Code Quality 検出結果が少なくとも 1 件あります。 pull request の準備ができていない場合は、次の例に従うことができます。
このチュートリアルでは、実行中の例を使用します。一部のコードをリファクタリングするプル要求では、コード品質の問題がそのままマージされている場合、既定のブランチにいくつかのコード品質の問題が導入されます。 Code Quality スキャンはプル要求で自動的に実行され、いくつかの結果がコメントとして報告されています。
pull request が検索を修正するのに最適な場所である理由
プル リクエストの段階で解決しない指摘事項はすべて、リポジトリのバックログの対応項目となり、技術的負債は今対処するよりも後で解消するほうがコストがかかることが少なくありません。 今なら、プルリクエストがオープンなうちに、コードのコンテキストや意図がまだ記憶に新しいため、各指摘とその自動修正をより迅速に評価し、適用し、あるいは自信を持って却下できます。
プルリクエストの段階で検出事項を解消することで、チームは機能開発と修正対応の優先順位付けに費やす時間を減らし、バックログを消化するためだけの追加のプルリクエストに伴うオーバーヘッドを回避できます。
手順 1: pull request で Code Quality コメントを見つける
pull request を開くと、Code Qualityは 2 種類の分析を実行し、結果をコメントとして投稿します。 プル リクエストの Files changed タブを開き、各コメントを誰が残したかを確認します。投稿者を見れば、それがどの種類の指摘かが分かります。
-
ルールベースの結果 は、
github-code-quality[bot]によって投稿されます。 Code Quality では、 CodeQL を使用して一連のルールに対して変更をスキャンし、各コメントには推奨される自動修正が含まれています。 -
AI を利用した結果 は、 Copilot によって投稿されます。 組織に Copilot ライセンスがあり、企業に対して AI 機能が有効になっている場合、 Copilotコード レビュー はルールベースの分析で見逃される可能性がある品質の問題を探します。 これらのコメントには、推奨される自動修正も含まれています。
この例では、 github-code-quality[bot]から得た 3 つのコメントを見て、ルールベースの結果を示します。 独自のプル要求では、両方の種類が表示される場合があります。これは、重大度ラベル (手順 2) がルールベースのコメントにのみ適用されるため、先に進む前に確認できます。
手順 2: 重大度ラベルを読んで、重要なものを決定する
github-code-quality[bot]からのすべてのルール ベースの検索には、重大度ラベル (エラー、警告、メモ) が含まれます。 コメントの 1 つでラベルを見つけて、このテーブルに対して確認します。
| Severity | Definition |
|---|---|
| エラー | バグ、障害、または主要な保守容易性リスクを引き起こす可能性が高い重大度の問題を示します。 |
| 警告 | コードの品質や信頼性に影響を与える可能性があるが、すぐには重要ではない中程度の重大度の問題を示します。 |
| メモ | 重大度の低い問題、軽微な改善、または推奨事項を示します。 これらの結果は、継続的なコードの正常性と保守容易性に役立ちます。 |
ラベルは、同時に2つの役割を果たしています。
- これは、最初に修正する内容を示します。 重大度は、一般的なコード全体でのルールの予想される影響を反映します。 この例では、 エラー、 警告から始めて、 ノート をオプションの研磨として扱います。
- マージをまったく実行できるかどうかを決定できます。 リポジトリ管理者または組織の所有者は、マージ ゲートとして Code Quality を構成できます。 たとえば、マージのしきい値が「警告以上」の場合、マージする前に、警告およびエラー レベルのすべての検出結果を修正または却下する必要があります（注記 レベルの検出結果はマージを妨げません）。 同様に、より厳しいしきい値の場合は、マージ前に_すべての_検出事項を解決する必要が生じる場合があります。
ゲートが有効かどうかを確認するには、プル要求の下部にある [チェック ] セクションまでスクロールします。 変更が必要なしきい値を下回った場合は、マージ ブロック バナーが表示されます。"マージはブロックされています: コード品質の結果が検出されました。"
![プル要求の [チェック] セクションのマージ ブロック バナーのスクリーンショット。](/assets/cb-72468/mw-1440/images/help/code-quality/code-quality-merge-block.webp)
この例では、ゲートは "警告以上" に設定されているため、バナーが表示されます。 エラー と 警告 によってマージがブロックされ、 メモ はブロックされていません。 これにより、このプル要求をマージする前に何をクリアする必要があるかがわかります。
マージ ブロック バナーで重大度レベルが指定されていない場合は、pull request をマージするために すべての 結果をクリアする必要があります。
手順 3: 各検出結果に対処する
すべての結果について、コードに適用されるかどうかを決定し、適用される場合は修正方法を決定します。 その結果、3 つのアクションのいずれかになります。
| Assessment | 推奨されるアクション | Notes |
|---|---|---|
| 結果は正当であり、推奨される修正プログラムは正しく見えます | ||
| 自動修正候補を適用する | ||
| コミット候補をクリックしてもAI creditsは使用されません。ルールベースの自動修正では、Copilotライセンスは必要ありません。 | ||
| 結果は実際ですが、一度に複数の修正を行うか、推奨される修正プログラムを適応させる必要があります | ||
| ** | ||
Copilot に委任**—コメントで @copilot にメンションして、作業をクラウドエージェントに引き継ぎます。 | ||
| Copilot | ||
| 👀と反応し、新しいエージェント セッションを開始し、必要な修正をプル要求のブランチにプッシュします | ||
| Copilotライセンスが必要で、AI creditsを使用します。 | ||
| 結果は適用されません。たとえば、テスト コード、意図的なパターン、誤検知などです。 | [ 検索結果を閉じる] をクリックし、理由を指定します | pull request をマージすることはできますが、その結果はリポジトリのバックログと今後のプル要求に表示されます。 |
このプラクティスを独自のプル要求に適用し、重大度順に動作します。
この例では、
- エラーレベルと警告レベルの結果は本物のバグであり、推奨される自動修正は妥当に見えるので、自動修正候補を適用します。 検出結果は解消され、ブロックカウントから除外されます。
- Note レベルの検出結果は、隣接するテストヘルパー内の軽微なパターンを示します。 意図的なものなので、"テストで使用" のような理由で無視します。
- 追加の Note レベルの検出事項がいくつかあります。 各自動修正候補を 1 つずつ処理する代わりに、"
@copilot、残りのすべてのノート レベルの結果を修正する" というコメントを付けます。 リポジトリの [Copilot] タブで**** の進行状況を追跡し、準備ができたら pull request にプッシュするコミットを確認します。
手順 4: pull request がブロック解除されていることを確認する (省略可能)
ブロッキングの指摘事項が実際にある場合は、関連する指摘事項を修正または却下したら、プル リクエストの下部にあるチェックセクションに戻ってください。
この例では、 エラー と 警告 の結果が解決されると、マージ ブロック バナーが消えます。 プルリクエストをマージできるようになりました。
バナーがまだ表示されている場合は、ブロッキング以上の重大度の検出結果がまだ未解決のままであることを意味します。
手順 5: AI を利用した結果を解決する Copilot
組織に Copilot ライセンスがあり、企業で AI 機能が有効になっている場合は、 Copilotによって投稿されたコメントも表示されます。 これらは、手順 1 で導入された AI を活用した結果であり、Copilotコード レビューではなくgithub-code-quality[bot]から得た結果です。
ルールベースの検出結果が、変更内容を固定された一連の CodeQL ルールに照らし合わせるのに対し、Copilotコード レビュー はコードの意図を推論します。 特定のルールにマップされない品質の問題をキャッチするため、ルールベースのコメントの代わりではなく、便利な補完として役立ちます。
これらの結果には、重大度ラベル "Error"、"Warning"、または "Note" は含まれません。 手順 2 で確認したマージ ゲートでは ルールベースの結果の重大度のみがカウントされるため、AI を利用した結果によってプル要求が単独でブロックされることはありません。 これでは省略可能にはなりません。コンテキストで解決することは、品質の問題を既定のブランチから除外するための最適な場所です。
手順 3 で使用したのと同じ 3 つの選択肢を使用して、AI を利用した検索を解決します。
- 自動修正候補を適用します。 各コメントには、推奨される修正プログラムが含まれています。 そのままで正しければ、提案を確定 をクリックします。 自動修正を適用しても、GitHub AI Creditsは消費されません。
- Copilot に委任—コメントで
@copilotにメンションして、作業をクラウド エージェントに任せます。 Copilot は、 👀と反応し、新しいエージェント セッションを開始し、必要な修正をプル要求のブランチにプッシュします。 このオプションでは、 Copilot ライセンスが必要であり、 GitHub AI Creditsを使用します。 - コメントを解決します。 コードに適用されない場合は、[ 解決] をクリックします。
これがコードヘルスの他の部分とどう関係するか
先ほどクリアした pull request は、より大きな画像の一部です。
- スコア。 リポジトリの信頼性と保守容易性のスコアは、既定のブランチの結果から計算されます。 マージの前に結果を解決することは、それらのスコアがドリフトしないようにする方法です。 「メトリックとスコアのリファレンス」を参照してください。
- バックログ。 pull request で修正しなかったものは、デフォルト ブランチ上の指摘事項のバックログに追加されます。 バックログを下げる作業は、それ自体の規範です。 「リポジトリのコード品質スコアを上げる」を参照してください。
- コンプライアンス。 結果のクラスが本当に既定のブランチに到達してはならない場合、"コード品質の結果を要求する" ルール セットは、リポジトリ管理者と組織の所有者がその決定をマージ ゲートとしてエンコードするのに役立ちます。 「pull request でのブロックの解決」を参照してください。
最も健全なチームは、この3つすべてを組み合わせています。つまり、プルリクエスト段階での意図的なトリアージと修正、定期的なバックログ対応、そしてマージ時におけるしきい値の厳格な適用です。
Troubleshooting
- Code Qualityコメントが表示されません。 スキャンがまだ実行されている場合、変更がサポートされている言語に触れない、または結果がない可能性があります。 Code Qualityが有効になっていることを確認し、完了までの時間 ("CodeQL - コード品質" と呼ばれます) を確認します。 「GitHub Code Quality の有効化」を参照してください。
github-code-quality[bot]のコメントしか表示されず、Copilotのコメントはまったく表示されません。 AI を活用した結果には、 Copilot ライセンスと AI 機能が企業で有効になっている必要があります。 これらの結果がない場合は、ルールベースの結果のみが表示されます。- コード品質の結果の自動修正が表示されません。 自動修正の生成はGitHub AI Creditsを消費します。 組織が毎月の AI credits予算を使い果たした可能性があります。
- マージ ブロックバナーはクリアされません。 ブロッカー重大度以上の検出結果が少なくとも1件、未解決のままです。 マージ ブロック バナーに重大度レベルが表示されていない場合は、リポジトリで最も厳しいコード品質のしきい値が使用されており、マージする前にすべての検出結果に対処する必要があることを意味します。 「pull request でのブロックの解決」を参照してください。
まとめ
このチュートリアルでは、pull request に関する Code Quality コメントを確認し、重大度を使用して修復の優先順位を付け、プル要求をマージする前に各検出を意図的に解決しました。 各検索とその自動修正を小さなコンテキスト内の決定として扱うことで、コード品質の負債が既定のブランチに到達するのを防ぐことができます。
次のステップ
- 既存のバックログ ( リポジトリのコード品質スコアを上げる) に同じ考え方を適用します。
- 結果をスコアに変換して、作業の影響を測定する方法について説明します: メトリックとスコアのリファレンス。