マルチリポジトリ バリアント分析を使用した大規模な CodeQL クエリの実行

マルチリポジトリ バリアント分析を使用した大規模な CodeQL クエリの実行について

マルチリポジトリ バリアント分析 (MRVA) では、Visual Studio Code で、CodeQL クエリを GitHub.com 上の最大 1,000 個のリポジトリの一覧に対して実行できます。

リポジトリの一覧に対して MRVA を実行すると、分析に使用できる CodeQL データベースを持つ各リポジトリに対してクエリが実行されます。 GitHub は、CodeQL を使用して code scanning を実行するすべてのリポジトリを含む、数千のパブリック リポジトリの既定のブランチ用の最新 CodeQL データベースを作成し、格納します。

分析のためにリストにリポジトリを追加する前に、既定または高度なセットアップで、GitHub.com に対して CodeQL を使用して code scanning を有効にする必要があります。 code scanning using CodeQL の有効化に関する詳細は、「Running CodeQL queries at scale with multi-repository variant analysis」をご覧ください。

MRVA が CodeQL データベースに対して GitHub.com に対してクエリを実行する仕組み

MRVA を実行すると、分析は GitHub Actions を使用して完全に実行されます。 ワークフローを作成する必要はありませんが、Visual Studio Code 拡張機能の CodeQL がコントローラー リポジトリとして使用する GitHub リポジトリを指定する必要があります。 各リポジトリの分析が完了すると、結果を表示するために VS Code に送信されます。

CodeQL 拡張機能は、ライブラリとライブラリの依存関係を含む CodeQL パックをビルドします。 CodeQL パックと選択したリポジトリ リストは、GitHub.com 上の API エンドポイントにポストされます。これによって、コントローラー リポジトリ内の GitHub Actions 動的ワークフローがトリガーされます。 ワークフローは複数の並列ジョブを起動して、リスト内のリポジトリに対して CodeQL クエリを実行し、クエリの実行を最適化します。 各リポジトリが分析されると、結果が処理され、VS Code に表示されます。

前提条件

• 最初のマルチリポジトリ バリアント分析を実行する前に、コントローラー リポジトリを定義する必要があります。

• コントローラー リポジトリは空でもかまいませんが、少なくとも 1 つのコミットが必要です。

• パブリック リポジトリを分析する場合、コントローラー リポジトリの可視性は "パブリック" にすることができます。 バリアント分析は無料です。

• プライベート リポジトリまたは内部リポジトリを分析する必要がある場合は、コントローラー リポジトリの可視性を "プライベート" にする必要があります。 無料制限を超えてバリアント分析で使用されたアクションは、リポジトリ オーナーに課金されます。 無料時間と請求について詳しくは、「GitHub Actions の課金について」をご覧ください。

MRVA 用のコントローラー リポジトリの設定

1. [バリアント分析リポジトリ] ビューで、[コントローラー リポジトリの設定] をクリックして、コントローラー リポジトリのフィールドを表示します。

   

2. コントローラー リポジトリとして使用する GitHub.com にリポジトリのオーナーと名前を入力し、Enter キーを押します。

3. GitHub で認証するように求められた場合は、指示に従って個人または組織のアカウントにログインします。 完了すると、GitHub 認証からのプロンプトが表示され、Visual Studio Code で開くためのアクセス許可が求められる場合があります。[開く] をクリックします。

コントローラー リポジトリの名前は、CodeQL 拡張機能の設定に保存されます。 コントローラー リポジトリを編集する方法については、「設定のカスタマイズ」を参照してください。

MRVA を使用した大規模なクエリの実行

1. 既定では、[バリアント分析リポジトリ] ビューには、分析する言語の GitHub.com の上位 10 個、上位 100 個、上位 1000 個のパブリック リポジトリの既定のリストが表示されます。

2. 必要に応じて、新しいリポジトリ、組織、リストを追加できます。 詳細については、「リポジトリのカスタム リストの作成」を参照してください。

3. クエリを実行する GitHub リポジトリを選択します (複数可)。

   

4. 実行するクエリを開き、クエリ ファイルで右クリックし、CodeQL: バリアント分析の実行 を選択してバリアント分析を開始します。

エラーと警告

MRVA を実行すると、エラーと警告が 2 つの主要な場所に表示されます。

• Visual Studio Code エラー: CodeQL パックを作成し、分析を GitHub.com に送信する際の問題は、アプリケーションの右下隅で Visual Studio Code エラーとしてレポートされます。 情報は、[問題] ビューでも確認できます。

• バリアント分析結果: バリアント分析の実行に関する問題は、このビューで報告されます。

結果の調査

GitHub でバリアント分析を実行するワークフローが実行されるとすぐに、[バリアント分析結果] ビューが開き、結果は準備され次第表示されます。 このビューを使用すると、進行状況の監視、エラーの確認、コントローラー リポジトリ内のワークフロー ログへのアクセスを行うことができます。

バリアント分析の実行がスケジュールされている場合、[結果] ビューは自動的に開きます。 最初に、このビューには、分析用にスケジュールされたすべてのリポジトリの一覧が表示されます。 各リポジトリが分析されると、ビューが更新され、結果の数の概要が表示されます。 リポジトリの詳細な結果 (結果パスを含む) を表示するには、リポジトリ名をクリックします。

リポジトリごとに、次の情報が表示されます。

• クエリで見つかる結果の数

• リポジトリの表示範囲

• 分析がまだ実行中か完了しているか

• リポジトリが GitHub に対して持つ星の数

リポジトリの結果の表示

1. リポジトリ名をクリックすると、各結果の概要が表示されます。

2. GitHub.com のソース ファイルへのリンクを使用して、各結果で確認できる情報を探索します。 データ フロー クエリの場合は、[パスの表示] リンクもあります。

   

結果をエクスポートする

結果をエクスポートしてさらに分析したり、コラボレーターと検討したりすることができます。 [結果] ビューで、[結果のエクスポート] をクリックして、結果を GitHub.com のシークレット gist またはワークスペース内の Markdown ファイルにエクスポートします。

分析のために単一の GitHub リポジトリまたは組織を選択する

1. [バリアント分析リポジトリ] ビューで、[+] をクリックして新しいデータベースを追加します。

2. ドロップダウン メニューから、[GitHub リポジトリ] または [GitHub 組織またはオーナーのすべてのリポジトリ] を選択します。

3. フィールドに、使用するリポジトリまたは組織の識別子を入力します。

リポジトリのカスタム リストの作成

1. [バリアント分析リポジトリ] ビューで、[リストの追加] アイコンをクリックします。

   

2. クエリの新しい名前を入力し、Enter キーを押します。

3. ビューでリストを選択し、[+] をクリックしてリポジトリをリストに追加します。

リポジトリのカスタム リストの管理

リスト名またはリスト内のリポジトリ名を右クリックし、コンテキスト メニューからオプションを選択することで、カスタム リストを管理および編集できます。

カスタム リストは、ワークスペース内の databases.json ファイルに格納されます。 このファイルを Visual Studio Code で直接編集する場合は、ビュー ヘッダーで {} をクリックすると開くことができます。

たとえば、クエリの結果を含むリポジトリのセットを引き続き分析する場合は、[バリアント分析結果] ビューの [リポジトリ リストのコピー] をクリックして、結果を含むリポジトリのみの一覧を JSON としてクリップボードに追加します。

次のスニペットの例では、my-organization/my-repository にクエリの結果が含まれています。

{
    "name": "new-repo-list",
    "repositories": [
        "my-organization/my-repository"
    ]
}

その後、[バリアント分析リポジトリ] ビューで簡単にアクセスできるように、databases.json へリポジトリの new-repo-list を挿入します。

GitHub Code Search を使用してカスタム リストにリポジトリを追加する

CodeQL 拡張機能でコード検索を直接使用して、GitHub.com のリポジトリのサブセットをカスタム リストに追加できます。

たとえば、GitHub 上の rails 組織内のすべてのリポジトリを追加するには、org:rails で検索します。

検索を行うごとに、最大 1,000 個のリポジトリをカスタム リストに追加できます。

1. [バリアント分析リポジトリ] ビューで、リポジトリを追加するリストを選択します。 新しいリストを作成することも、リポジトリが既に含まれている既存のリストを選択することもできます。

2. 選択したリストを右クリックし、[GitHub Code Search でリポジトリを追加する] をクリックします。

3. アプリケーションの上部に表示されるポップアップで、検索バーの下にあるドロップダウンの選択肢から検索する言語を選択します。

4. 検索バーに、使用する検索クエリを入力し、Enter キーを押します。

テキスト Searching for repositories... が表示されたボックスで、アプリケーションの右下隅に検索の進行状況を表示できます。 [キャンセル] をクリックすると、リポジトリは一覧に追加されません。 完了すると、結果のリポジトリが [バリアント分析リポジトリ] ビューのカスタム リストの下のドロップダウンに表示されます。

結果として得られるリポジトリの中には、CodeQL データベースが含まれていないものがあり、一部のリポジトリは Visual Studio Code の CodeQL 拡張機能によるアクセスを許可しない場合があります。 リストで分析を実行すると、[バリアント分析結果] ビューに、分析されたリポジトリ、アクセスが拒否されたリポジトリ、CodeQL データベースが存在しなかったリポジトリが表示されます。