Skip to main content

Pull RequestでCode scanningアラートをトリアージする

Pull Requestで code scanning が問題を特定した場合、強調表示されたコードを確認してアラートを解決できます。

この機能を使用できるユーザーについて

If you have read permission for a repository, you can see annotations on pull requests. With write permission, you can see detailed information and resolve code scanning alerts for that repository.

Code scanning は、GitHub.com のすべてのパブリック リポジトリに使用できます。 Organization によって所有されるプライベート リポジトリで code scanning を使うには、GitHub Advanced Security のライセンスが必要です。 詳しくは、「GitHub Advanced Security について」を参照してください。

Pull Requestの code scanning 結果について

プルリクエストのチェック用に code scanning が設定されているリポジトリでは、code scanningがプルリクエストのコードをチェックします。 デフォルトでは、このチェックはデフォルトブランチを対象とするプルリクエストに限定されていますが、この設定は GitHub Actions またはサードパーティの CI/CD システム内で変更できます。

pull request で変更されたコード行によって code scanning アラートが生成された場合、アラートは pull request の次の場所にレポートされます。。

  • pull request のチェック結果
  • pull request の [会話] タブ (pull request レビューの一部として)
  • pull request の [変更されたファイル] タブ

注: Code scanning では、pull request 差分にアラートによって識別されたすべてのコード行が存在する場合にのみ、pull request にアラートが表示されます。 詳しくは、「Code scanningの SARIF サポート」を参照してください。

リポジトリへの書き込み権限がある場合は、 [セキュリティ] タブに既存の code scanning アラートが表示されます。リポジトリ アラートの詳細については「リポジトリのコード スキャンのアラートを管理する」を参照してください。

タイム コードがプッシュされるたびにスキャンされるように code scanning が設定されているリポジトリでは、code scanning の結果がすべてのオープンな pull request にマップされ、アラートは他の pull request でチェックされるのと同じ場所にアノテーションとして追加されます。 詳しくは、「をカスタマイズして、コード スキャンの詳細設定を行う」を参照してください。

pull request が code scanning を使用する保護されたブランチをターゲットとし、リポジトリの所有者が必要な状態チェックを設定している場合、pull request をマージする前に "Code scanning の結果" チェックに合格する必要があります。 詳しくは、「保護されたブランチについて」を参照してください。

Pull Requestのチェックとしての code scanning について

code scanning を pull request のチェックとして構成するためのオプションは多数あるので、厳密な構成はそれぞれのリポジトリで異なり、複数のチェックを行う場合もあります。

Code scanning の結果チェック

code scanning のすべての構成で、code scanning の結果を含むチェックが、 Code scanning の結果です。 使用される分析ツールの結果はそれぞれ個別に表示されます。 pull request で変更されたコード行に対する新しいアラートは、注釈として表示されます 。

分析されたブランチのアラートの完全なセットを表示するには、 [すべてのブランチ アラートを表示する] をクリックします。 これにより、ブランチのすべてのアラートを種類、重大度、タグなどでフィルタリングできる完全なアラート ビューが開きます。詳細については、「リポジトリのコード スキャンのアラートを管理する」を参照してください。

pull request の Code scanning 結果チェックのスクリーンショット。 [すべてのブランチ アラートを表示する] リンクが濃いオレンジ色の枠線で囲まれています。

Code scanning の結果チェックのエラー

code scanning の結果チェックで、重大度が errorcritical、または high の問題が検出された場合、チェックは失敗し、チェック結果にエラーが報告されます。 code scanning で検出されたすべての結果の重大度が低い場合、アラートは警告または通知として扱われ、チェックは成功となります。

pull request のマージ ボックスのスクリーンショット。 [コード スキャン結果 / CodeQL] チェックの横には [新しいアラートが 1 件、その中で重大度が高のセキュリティ...] があります。

リポジトリ設定でデフォルトの動作をオーバーライドできます。そのためには、重大度のレベルと、pull request のチェック エラーが発生するセキュリティ重大度を指定します。 詳しくは、「をカスタマイズして、コード スキャンの詳細設定を行う」をご覧ください。

その他のcode scanning チェック

設定によっては、code scanning が設定された pull request で実行される追加のチェックが表示される場合があります。 これらは通常、コードを分析する、またはcode scanning の結果をアップロードするワークフローです。 これらのチェックは、分析に問題がある場合のトラブルシューティングに役立ちます。

たとえば、リポジトリが CodeQL 分析ワークフロー を使用している場合、 CodeQL / 分析 (言語) チェックを各言語で実行してから、結果チェックを実行します。 設定に問題がある場合、解析がコンパイルする必要がある言語 (C/C++、C#、Java など) でプルリクエストがビルドを中断している場合、解析は失敗することがあります。

その他の pull request のチェックと同様に、 [チェック] タブでチェック エラーの完全な詳細情報を確認できます。構成とトラブルシューティングの詳細については、「をカスタマイズして、コード スキャンの詳細設定を行う」または「code scanning のトラブルシューティング」を参照してください。

pull request でのアラートの表示

pull request に導入された code scanning アラート のうち変更の差分に含まれるものは、 [会話] タブで表示できます。Code scanning は、各アラートを、アラートをトリガーしたコード行の注釈として表示する pull request レビューを投稿します。 注釈から直接、アラートにコメントを付け、アラートを無視し、アラートのパスを表示できます。 アラートの詳細を表示するには、[詳細の表示] リンクをクリックします。すると、アラートの詳細ページに移動します。

pull request の [会話] タブのアラート注釈のスクリーンショット。 [詳細の表示] リンクが濃いオレンジ色の枠線で囲まれています。

pull request の [変更されたファイル] タブ

pull request に新しいコード スキャン構成を追加すると、pull request にコメントが表示され、リポジトリの [セキュリティ] タブに移動して、pull request ブランチのすべてのアラートを表示できます。 リポジトリのアラートの表示について詳しくは、「リポジトリのコード スキャンのアラートを管理する」を参照してください。

リポジトリへの書き込み権限がある場合、一部のアノテーションにはアラートの追加的な背景を説明するリンクが含まれています。 上の例では、CodeQL 分析から [ユーザー指定の値] をクリックすると、データ フローに信頼されていないデータが入っている場所 (ソース) が表示されます。 この場合、 [パスの表示] をクリックすることで、ソースからデータ (シンク) を使用するコードまでのフル パスを表示することもできます。 これにより、データが信頼されていないかや、ソースとシンクの間のデータサニタイズのステップを解析が認識できなかったかを簡単に確認できます。 CodeQL を使用したデータ フローの分析については、「データ フロー分析について」を参照してください。

アラートの詳細情報を表示するには、書き込み権限を持つユーザが、アノテーションに表示されている [詳細を表示] のリンクをクリックします。 これにより、ツールが提供するコンテキストとメタデータのすべてをアラートビューで確認できます。 下の例では、問題の重要度、タイプ、および関連する共通脆弱性タイプ一覧 (CWE) を示すタグが表示されています。 また、どのコミットが問題を引き起したかも表示されています。

[アラート] ページのステータスと詳細は、他のブランチにアラートが存在する場合であっても、リポジトリの既定のブランチに対するアラートのステータスを反映するのみです。 既定以外のブランチのアラートの状態は、[アラート] ページの右側にある [影響を受けるブランチ] セクションで確認できます。 既定のブランチにアラートが存在しない場合、アラートの状態は、[in pull request] または [in branch] として、グレー表示されます。

アラートの詳細画面において、CodeQL 分析のような一部のcode scanning ツールでは、問題の説明や、コードを修正する方法を説明するための [詳細を表示] リンクも含まれています。

code scanning アラートの説明を示すスクリーンショット。 [詳細を表示] というラベルが付いたリンクが濃いオレンジ色の枠線で囲まれています。

pull request のアラートに対するコメント

pull request に表示されるすべての code scanning アラート に対してコメントすることができます。 アラートは、pull request レビューの一部として pull request の [会話] タブに注釈として表示され、 [変更されたファイル] タブにも表示されます。

pull request をマージする前に pull request でのすべての会話 (code scanning アラートに関するものを含む) を解決するように要求することを選べます。 詳しくは、「保護されたブランチについて」を参照してください。

Pull Requestのアラートの修正

プルリクエストへのプッシュアクセスがあるユーザなら誰でも、プルリクエストで特定された code scanning アラートを解決できます。 プルリクエストに変更をコミットすると、プルリクエストのチェック実行が新しくトリガーされます。 問題を修正すると、アラートはクローズし、アノテーションは削除されます。

アラートの自動修正候補の操作

注: code scanning の GitHub の自動修正はベータ版です。 機能とドキュメントテーションは変更される場合があります。 このフェーズでは、機能は、CodeQL によって識別される JavaScript、TypeScript、Python、Java アラートに制限されます。 エンタープライズ アカウントがあり、GitHub Advanced Security を使用している場合、エンタープライズはベータ版にアクセスできます。

自動修正は、code scanning の GitHub Copilot 搭載による拡張であり、pull request 内の code scanning アラートを修正するのに役立つ、ターゲットを絞った推奨事項を提供します。 潜在的な修正は、コードベース、pull request、および CodeQL 分析からのデータを使用して、大規模な言語モデル (LLM) によって自動的に生成されます。

pull request の code scanning アラートのチェック エラーのスクリーンショット。 アラートの "自動修正" 候補の最初の段落が濃いオレンジ色でハイライトされています。

自動修正候補の生成と pull request への発行

リポジトリに対して自動修正が有効になっている場合、アラートは通常どおり pull request に表示され、CodeQL によって検出されたすべてのアラートからの情報が自動的に LLM に送信され、処理されます。 LLM 分析が完了すると、すべての結果が関連するアラートに対するコメントとして発行されます。 詳しくは、「CodeQL コード スキャンの自動修正について」を参照してください。

注: 自動修正では、CodeQL クエリのサブセットがサポートされます。 分析が完了すると、関連するすべての結果が一度に pull request に発行されます。 pull request 内の少なくとも 1 つのアラートに自動修正候補がある場合は、LLM がコードについて潜在的な修正の特定を完了したと想定されます。

通常、pull request に変更を提案するときには、pull request で変更された 1 つのファイルに対する変更をコメントに含めます。 次のスクリーンショットは、アラートが表示される index.js ファイルへの変更を提案する自動修正コメントを示しています。 潜在的な修正には escape-html に関する新しい依存関係が必要であるため、元の pull request が package.json ファイルに変更を加えない場合でも、コメントはこの依存関係をこのファイルに追加することも提案します。

現在のファイルの説明と提案された修正を示すアラートの自動修正候補のスクリーンショット。 追加ファイル "package.json" に対して提案された変更は、濃いオレンジで囲まれています。

自動修正候補の評価とコミット

各自動修正候補は、コードベース内の code scanning アラートに対する潜在的なソリューションを示しています。 提案された変更を評価して、それらがコードベースに適したソリューションであるかどうかを判断し、意図した動作が維持されていることを確認する必要があります。 自動修正候補の制限については、「CodeQL code scanning の自動修正について」の「自動修正候補の制限事項」および「自動修正候補の制限の緩和」を参照してください。

  1. [編集] をクリックして編集オプションを表示し、希望する方法を選択します。
    • 提案された修正が適用されたブランチを示す codespace を開くには、[codespace で編集] を選択します。
    • 提案された修正をローカル リポジトリまたはブランチに適用する手順を表示するには、[GitHub CLI でローカルに編集] を選択します。
  2. 必要に応じて、提案された修正をテストして変更します。
  3. 変更のテストが完了したら、変更をコミットして、ブランチにプッシュします。
  4. 変更をブランチにプッシュすると、pull request に対するすべての通常のテストがトリガーされます。 単体テストに以前と同じくパスすることと、code scanning アラートが修正されたことを確認します。

自動修正候補を閉じる

自動修正候補を却下する場合は、コメントの [修正候補を閉じる] をクリックして、提案された修正を閉じます。

Pull Requestのアラートの却下

アラートをクローズする別の方法として、却下する方法があります。 修正する必要がないと考えられる場合は、アラートを却下できます。 たとえば、テストで使われるだけのコードのエラーや、エラーを修正するための労力がコードを改善することによる潜在的な利点よりも大きい場合です。 リポジトリに書き込み権限を持っているなら、コードのアノテーションとアラートのサマリで [アラートの却下] ボタンが利用できます。 [アラートの却下] をクリックすると、アラートをクローズする理由の選択が求められます。

pull request のコード スキャン アラートのチェックエラーのスクリーンショット。 チェックエラーの [アラートの却下] ボタンが濃いオレンジ色で囲まれています。 [アラートの却下] ドロップダウンが表示されます。 クエリが将来の分析に含まれ続けるかに影響することがあるので、ドロップダウンメニューから適切な理由を選択することは重要です。 必要に応じて、無視にコメントを付けて、アラートを無視するコンテキストを記録できます。 無視のコメントはアラート タイムラインに追加され、監査と報告の間に正当な理由として使用できます。 コード スキャン REST API を使用して、コメントを取得または設定できます。 コメントは、alerts/{alert_number} エンドポイントの dismissed_comment に含まれます。 詳しくは、「コード スキャン用の REST API エンドポイント」を参照してください。

たとえばコードがサポートされていないサニタイズ ライブラリを使っているといった理由で、CodeQL のアラートを擬陽性の結果として却下する場合、CodeQL に貢献して分析を改善することを検討してください。 CodeQL の詳細については、「CodeQL に貢献する」を参照してください。

アラートの却下の詳細については、「リポジトリのコード スキャンのアラートを管理する」を参照してください。