# コード品質の問題が既定のブランチに到達するのを防ぐ

プルリクエスト上の Code Quality 検出結果を確認しながら、重大度ラベルを理解し、各検出結果を修正、委任、または却下するのに最適なタイミングと、それらの選択がリポジトリのコードの健全性にどのように影響するかを学びます。

## はじめに

このチュートリアルでは、最初のコメントからマージまで、 Code Qualityの分析を通じて 1 つのプル要求に従います。 学習内容:

* pull request で Code Quality コメントを読み取る方法。
* 検出事項の重大度ラベルを使用して、何を修正し、何を却下し、どの順序で対応するかを決定する方法。
* プル要求で行った選択によって、リポジトリのスコア、バックログ、マージ ゲートがどのように形成されるか。

最後に、サンプルの pull request でブロックされたすべての検出を解決し、クリーンな Code Quality チェックでマージし、各選択を行った *理由* を理解できます。

これはガイド付きチュートリアルであるため、速度よりも理解が優先されます。 自動修正をコミットする方法や検出結果を却下する方法の基本的な手順については、関連するハウツー [pull request でのコード品質の結果の修正](/ja/code-security/how-tos/maintain-quality-code/fix-findings-on-a-pr) を参照してください。

### 開始する前に

* Code Quality は、投稿するリポジトリで有効になっています。 「[GitHub Code Quality の有効化](/ja/code-security/how-tos/maintain-quality-code/enable-code-quality)」を参照してください。
* リポジトリでは、ルールベースの結果とスコアが生成されるように、 CodeQL でサポートされている言語が使用されます。 サポートされている言語の一覧については、 [GitHub のコード品質](/ja/code-security/concepts/code-quality/code-quality#supported-languages) を参照してください。
* 既定ブランチに対して、トリアージが必要な Code Quality の不具合が 1 件以上含まれたプル要求が未処理の状態です。 pull request の準備ができていない場合は、次の例に従うことができます。

このチュートリアルでは、実行中の例を使用します。一部のコードをリファクタリングするプル要求では、コード品質の問題がそのままマージされている場合、既定のブランチにいくつかのコード品質の問題が導入されます。
Code Quality スキャンはプル要求で自動的に実行され、いくつかの結果がコメントとして報告されています。

## pull request が検索を修正するのに最適な場所である理由

プル リクエストの段階で解決しない指摘事項はすべて、リポジトリのバックログの対応項目となり、技術的負債は今対処するよりも後で解消するほうがコストがかかることが少なくありません。 今なら、プルリクエストがオープンなうちに、コードのコンテキストや意図がまだ記憶に新しいため、各指摘とその自動修正をより迅速に評価し、適用し、あるいは自信を持って却下できます。

プルリクエストの段階で検出事項を解消することで、チームは機能開発と修正対応の優先順位付けに費やす時間を減らし、バックログを消化するためだけの追加のプルリクエストに伴うオーバーヘッドを回避できます。

## 手順 1: pull request で Code Quality コメントを見つける

pull request を開くと、 Code Quality は CodeQL を使用して、一連のルールに対して変更をスキャンし、結果をコメントとして `github-code-quality[bot]`投稿します。 各コメントには、推奨される自動修正が含まれています。 pull request の \[Files changed]\( **変更されたファイル** ) タブを開いて、結果を確認します。

この例では、 `github-code-quality[bot]`から 3 つのコメントを確認します。 それぞれの重大度ラベルに注意してください。 手順 2 では、その意味について説明します。

## 手順 2: 重大度ラベルを読んで、重要なものを決定する

`github-code-quality[bot]`からのすべての結果には、重大度ラベル (**エラー**、**警告**、メモ) が含**まれます**。 コメントの 1 つでラベルを見つけて、このテーブルに対して確認します。

| Severity | Definition                                                    |
| -------- | ------------------------------------------------------------- |
| **エラー**  | バグ、障害、または主要な保守容易性リスクを引き起こす可能性が高い重大度の問題を示します。                  |
| **警告**   | コードの品質や信頼性に影響を与える可能性があるが、すぐには重要ではない中程度の重大度の問題を示します。           |
| **メモ**   | 重大度の低い問題、軽微な改善、または推奨事項を示します。 これらの結果は、継続的なコードの正常性と保守容易性に役立ちます。 |

ラベルは、同時に2つの役割を果たしています。

1. **これは、最初に修正する内容を示します。** 重大度は、一般的なコード全体でのルールの予想される影響を反映します。 この例では、 **エラー**、 **警告**から始めて、 **ノート** をオプションの研磨として扱います。
2. **マージをまったく実行できるかどうかを決定できます。** リポジトリ管理者または組織の所有者は、マージ ゲートとして Code Quality を構成できます。 たとえば、マージのしきい値が「**警告***以上*」の場合、マージする前に、**警告***および*エラー レベルのすべての検出結果を修正または却下する必要があります（注記 レベルの検出結果はマージを妨げません）。 同様に、より厳しいしきい値の場合は、マージ前に\_すべての\_検出事項を解決する必要が生じる場合があります。

ゲートが有効かどうかを確認するには、プル要求の下部にある **\[チェック** ] セクションまでスクロールします。 変更が必要なしきい値を下回った場合は、マージ ブロック バナーが表示されます。"マージはブロックされています: コード品質の結果が検出されました。"

![プル要求の \[チェック\] セクションのマージ ブロック バナーのスクリーンショット。](/assets/images/help/code-quality/code-quality-merge-block.png)

この例では、ゲートは "警告以上" に設定されているため、バナーが表示されます。 **エラー** と **警告** によってマージがブロックされ、 **メモ** はブロックされていません。 これにより、このプル要求をマージする前に何をクリアする必要があるかがわかります。

マージ ブロック バナーで重大度レベルが指定されていない場合は、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 がブロック解除されていることを確認する (省略可能)

ブロッキングの指摘事項が*実際に*ある場合は、関連する指摘事項を修正または却下したら、プル リクエストの下部にある**チェック**セクションに戻ってください。

この例では、 **エラー** と **警告** の結果が解決されると、マージ ブロック バナーが消えます。 プル要求は、マージ可能になりました。

バナーがまだ表示されている場合は、ブロッキング以上の重大度の検出結果がまだ未解決のままであることを意味します。

## これがコードヘルスの他の部分とどう関係するか

先ほどクリアした pull request は、より大きな画像の一部です。

* **スコア。** リポジトリの信頼性と保守容易性のスコアは、既定のブランチの結果から計算されます。 マージの前に結果を解決することは、それらのスコアがドリフトしないようにする方法です。 「[メトリックとスコアのリファレンス](/ja/code-security/reference/code-quality/metrics-and-ratings)」を参照してください。
* **バックログ。** pull request で修正しなかったものは、デフォルト ブランチ上の指摘事項のバックログに追加されます。 バックログを下げる作業は、それ自体の規範です。 「[リポジトリのコード品質スコアを上げる](/ja/code-security/tutorials/improve-code-quality/raise-your-quality-rating)」を参照してください。
* **コンプライアンス。** 結果のクラスが本当に既定のブランチに到達してはならない場合、"コード品質の結果を要求する" ルール セットは、リポジトリ管理者と組織の所有者がその決定をマージ ゲートとしてエンコードするのに役立ちます。 「[pull request でのブロックの解決](/ja/code-security/how-tos/maintain-quality-code/unblock-your-pr)」を参照してください。

最も健全なチームは、この3つすべてを組み合わせています。つまり、プルリクエスト段階での意図的なトリアージと修正、定期的なバックログ対応、そしてマージ時におけるしきい値の厳格な適用です。

## Troubleshooting

* **Code Qualityコメントが表示されません。** スキャンがまだ実行されている場合、変更がサポートされている言語に触れない、または結果がない可能性があります。 Code Qualityが有効になっていることを確認し、完了までの時間 ("CodeQL - コード品質" と呼ばれます) を確認します。 「[GitHub Code Quality の有効化](/ja/code-security/how-tos/maintain-quality-code/enable-code-quality)」を参照してください。
* **コード品質の結果の自動修正が表示されません。** 自動修正の生成はGitHub AI Creditsを消費します。 組織が毎月の AI credits予算を使い果たした可能性があります。
* **マージ ブロックバナーはクリアされません。** ブロッカー重大度以上の検出結果が少なくとも1件、未解決のままです。 マージ ブロック バナーに重大度レベルが表示されていない場合は、リポジトリで最も厳しいコード品質のしきい値が使用されており、マージする前に*すべての*検出結果に対処する必要があることを意味します。 「[pull request でのブロックの解決](/ja/code-security/how-tos/maintain-quality-code/unblock-your-pr)」を参照してください。

## まとめ

このチュートリアルでは、pull request に関する Code Quality コメントを確認し、重大度を使用して修復の優先順位を付け、プル要求をマージする前に各検出を意図的に解決しました。 各検索とその自動修正を小さなコンテキスト内の決定として扱うことで、コード品質の負債が既定のブランチに到達するのを防ぐことができます。

## 次のステップ

* 既存のバックログ ( [リポジトリのコード品質スコアを上げる](/ja/code-security/tutorials/improve-code-quality/raise-your-quality-rating)) に同じ考え方を適用します。
* 結果をスコアに変換して、作業の影響を測定する方法について説明します: [メトリックとスコアのリファレンス](/ja/code-security/reference/code-quality/metrics-and-ratings)。