リポジトリの code scanning を構成する

code scanning を構成するためのオプション

code scanning アラートの生成方法、および使用するツールを、リポジトリレベルで決定できます。 GitHub AE は、CodeQL 解析のために完全に統合されたサポートを提供すると共に、サードパーティーのツールを使用した解析もサポートします。 詳しくは、次の箇条書きと「コード スキャンについて」をご覧ください。

• CodeQL : GitHub Actions (以下を参照) を使うか、またはサードパーティの継続的インテグレーション (CI) システム (「CIシステムでのCodeQL Code scanningについて」を参照) で CodeQL 分析を実行します。

• サードパーティ: GitHub Actions またはサードパーティのツールを使って、結果を GitHub AE にアップロードします (「SARIF ファイルを GitHub にアップロードする」を参照)。

  複数の構成を使用してコード スキャンを実行する場合、アラートに複数の分析元が含まれることがあります。 アラートに複数の分析元がある場合、各分析元でのアラートの状態を、[アラート] ページに表示することができます。 詳しくは、「Code scanningアラートについて」を参照してください。

前提条件

リポジトリの code scanning を構成する前に、リポジトリで使用できるセルフホステッド GitHub Actions ランナーが少なくとも 1 つ存在している必要があります。

セルフホスト ランナーを追加できるのは、企業の所有者、組織、リポジトリの管理者です。 詳細については、「セルフホステッド ランナーの概要」および「自己ホストランナーの追加」を参照してください。

code scanning の手動構成

1. ご自分のエンタープライズ で、リポジトリのメイン ページへ移動します。 1. リポジトリ名の下にある [ セキュリティ] をクリックします。 [セキュリティ] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [セキュリティ] をクリックします。

2. [ アラート] の右側にある [code scanning のセットアップ] をクリックします。code scanning アラートが見つからない場合は、Organization の所有者またはリポジトリ管理者に GitHub Advanced Security を有効にするよう依頼する必要があります。詳しくは、「Organization のセキュリティおよび分析設定を管理する」または「リポジトリのセキュリティと分析設定を管理する」をご覧ください。

3. [code scanning の使用を開始する] で、CodeQL 分析ワークフローまたはサードパーティ ワークフローに対して [このワークフローを設定する] をクリックします。 ワークフローは、それがリポジトリで検出されたプログラミング言語に関連する場合にのみ表示されます。 CodeQL 分析ワークフローは常に表示されますが、[このワークフローを設定する] ボタンは、CodeQL 分析がリポジトリ内に存在する言語をサポートしている場合にのみ有効になります。

4. code scanning がコードをスキャンする方法をカスタマイズするため、ワークフローを編集します。

   通常は、何も変更せずに CodeQL 分析ワークフローをコミットてきます。 ただし、サード パーティのワークフローの多くでは、追加の構成が必要になるので、コミットする前にワークフローのコメントを読んでください。

   詳しくは、「code scanning のカスタマイズ」を参照してください。

5. Start commit ドロップダウンを使用し、コミット メッセージを入力します。

6. 既定のブランチに直接コミットするか、新しいブランチを作成して pull request を開始するかを選択します。

7. [Commit new file] (新しいファイルをコミットする) または [Propose new file] (新しいファイルを提案する) をクリックします。

推奨される CodeQL 分析ワークフローでは、code scanning は、既定のブランチまたは保護されたブランチに変更をプッシュするたび、あるいは既定のブランチに pull request を生成するたびに、コードを解析するよう構成されています。 その結果として、code scanning が開始されます。

コード スキャンの on:pull_request と on:push トリガーは、それぞれ異なる目的に役立ちます。 詳しくは、「code scanning のカスタマイズ」を参照してください。

code scanning の一括構成

スクリプトを使って、code scanning を多くのリポジトリで一括で構成できます。 スクリプトを使用して、GitHub Actions ワークフローを複数のリポジトリに追加する pull request を発生させる場合は、jhutchings1/Create-ActionsPRs リポジトリで PowerShell を使用する例を、または、PowerShell を持たず代わりに NodeJS を使用したいチームの場合は nickliffen/ghas-enablement を参照してください。

code scanning からログ出力を表示する

リポジトリで code scanning を構成したら、実行したアクションの出力を見ることができます。

1. リポジトリ名の下の [Actions] (アクション) をクリックします。

   code scanning ワークフローを実行するためのエントリを含むリストが表示されます。 エントリのテキストは、コミットメッセージに付けるタイトルです。

   

2. code scanning ワークフローのエントリをクリックします。

3. 左側のジョブ名をクリックします。 たとえば、 [分析 (言語)] です。

   

4. このワークフローの実行時にアクションから出力されるログを確認します。

5. すべてのジョブが完了すると、確認されたすべての code scanning アラートの詳細を表示できます。 詳しくは、「リポジトリのコード スキャンのアラートを管理する」を参照してください。

Pull Requestのチェックを理解する

プルリクエストで実行するよう設定した各 code scanning ワークフローでは、プルリクエストのチェックセクションに常に最低 2 つのエントリが表示されています。 ワークフローの解析ジョブごとに 1 つのエントリがあり、最後のエントリは解析結果です。

code scanning 解析チェックの名前は、「ツール名 / ジョブ名 (トリガー)」という形式になります。 たとえば、C++ のコードの CodeQL 解析には、「CodeQL / Analyze (cpp) (pull_request)」のエントリがあります。 code scanning 分析エントリで [詳細] をクリックして、ログのデータを表示できます。 これにより、解析ジョブが失敗した場合に問題をデバッグできます。 たとえば、コンパイル型言語の code scanning 解析では、アクションがコードをビルドできなかった場合に解析ジョブが失敗します。

code scanning ジョブが完了すると、 GitHub はプルリクエストにより追加されたアラートがないか確認し、チェックのリストに「 の結果 / ツール名」のエントリを追加します。 code scanning が 1 回でも実行された後は、 [詳細] をクリックして分析結果を表示できます。

pull request を使用してリポジトリに code scanning を追加した場合、" の結果/ツール名" チェックの [詳細] をクリックすると、最初は "分析が見つかりません" というメッセージが表示されます。

テーブルには、1 つ以上のカテゴリが一覧表示されます。 各カテゴリは、同じツールとコミットに対して、異なる言語またはコードの別の部分で実行される特定の分析に関連しています。 このテーブルは、各カテゴリについて、code scanning が比較を試みた 2 つの分析を表し、pull request で導入または修正されたアラートを特定します。

たとえば、上のスクリーンショットでは、code scanning は pull request のマージ コミットの分析を検出しましたが、メイン ブランチの先頭の分析は検出しませんでした。

「分析が見つかりません」のメッセージが出る理由

プルリクエストのコードを解析した後、code scanning はトピックブランチ (プルリクエストを作成するために使用したブランチ) の解析と、ベースブランチ (プルリクエストをマージするブランチ) の解析を比較する必要があります。 これにより、code scanning はプルリクエストにより新しく発生したアラートはどれか、ベースブランチに既に存在していたアラートはどれか、また既存のアラートがプルリクエストの変更により修正されたかを測定できます。 始めにプルリクエストを使用してリポジトリに code scanning を追加した段階では、ベースブランチはまだ解析されていないので、こうした情報を測定できません。 この場合、pull request の結果チェックをクリックすると、"分析が見つかりません" いうメッセージが表示されます。

この他にも、プルリクエストのベースブランチに対する直近のコミットで解析結果がないことがあります。 これには以下が含まれます。

• プルリクエストがデフォルトブランチ以外のブランチに発行され、このブランチが解析されていない。

  ブランチがスキャン済みかを確認するには、 ページに移動し、 [ブランチ] ドロップダウンをクリックして該当するブランチを選択します。

  

  この状況における解決策は、そのブランチの code scanning ワークフローにある on:push と on:pull_request の指定にベースブランチの名前を追加してから、スキャンするオープンな pull request を更新するよう変更することです。

• プルリクエストのベースブランチへの直近のコミットが現在解析中で、解析がまだ利用できない。

  数分待ってからプルリクエストに変更をプッシュして、code scanning を再トリガーします。

• ベースブランチの直近のコミットを解析中にエラーが発生し、そのコミットの解析ができない。

  ちょっとした変更をベースブランチにマージして、この最新のコミットで code scanning をトリガーしてから、プルリクエストに変更をプッシュして code scanning を再トリガーします。

次の手順

code scanning を構成し、そのアクションを完了させた後は、次のことができます。

• リポジトリに対して生成された code scanning アラートをすべて表示する。 詳しくは、「リポジトリのコード スキャンのアラートを管理する」を参照してください。
• code scanning の構成後に送信された pull request に対して生成されたアラートを表示する。 詳しくは、「Pull RequestでCode scanningアラートをトリアージする」を参照してください。
• 実行完了の通知を構成する。 詳しくは、「通知を設定する」を参照してください。
• code scanning分析が生成したログを表示する。 詳しくは、「Code scanningログの表示」を参照してください。
• CodeQL code scanning の初期構成で発生した問題を調査する。 詳しくは、「CodeQL ワークフローのトラブルシューティング」を参照してください。
• code scanning がリポジトリ内のコードをスキャンする方法をカスタマイズする。 詳しくは、「code scanning のカスタマイズ」を参照してください。