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

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

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

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

分析のためにリストにリポジトリを追加する前に、既定または高度なセットアップで、GitHub に対して CodeQL を使用して code scanning を有効にする必要があります。 CodeQL を使用した code scanning の有効化の詳細については、「コード スキャンの既定セットアップの構成」を参照してください。

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

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

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

前提条件

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

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

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

• GitHub.com でプライベート リポジトリまたは内部リポジトリを分析する必要がある場合は、コントローラー リポジトリの可視性を "プライベート" にする必要があります。

無料制限を超えるプライベート リポジトリまたは内部リポジトリでバリアント分析を実行するために使用するアクション (分) はすべて、リポジトリの所有者に課金されます。 無料時間と請求に関する詳細については、「GitHub Actions の課金」を参照してください。

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

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

   

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

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

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

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

1. 既定では、[バリアント分析リポジトリ] ビューには、分析する言語の GitHub.com の上位 10 個、上位 100 個、上位 1000 個のパブリック リポジトリの既定のリストが表示されます。 コントローラー リポジトリが SUBDOMAIN.ghe.com でホストされている場合、これらのリストは使用できません。

2. 必要に応じて、新しいリポジトリ、組織、リストを追加できます。

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

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

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

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

   

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

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

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

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

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

エラーと警告

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

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

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

結果の調査

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

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

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

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

• リポジトリの表示範囲

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

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

リポジトリの結果の表示

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

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

   

結果をエクスポートする

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

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

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 のリポジトリのサブセットをカスタム リストに追加できます。

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

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

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

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

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

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

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

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

セルフホステッド ランナー上でマルチリポジトリ バリアント分析を使って CodeQL クエリを実行する

セルフホステッド ランナーでマルチ リポジトリ バリアント分析を使って CodeQL クエリを実行するには、まずセルフホステッド ランナーをコントローラー リポジトリに追加していることを確認するか、コントローラー リポジトリが organization レベルまたは Enterprise レベルのランナーにアクセスできることを確認する必要があります。

次に、使うセルフホステッド ランナーの JSON 形式のラベル一覧を含め、MRVA_RUNNER_OS という新しいアクション リポジトリ変数をコントローラー リポジトリに追加する必要があります。 次に例を示します。

["self-hosted", "macOS", "ARM64"]

詳細については、「自己ホストランナーの追加」および「グループを使用してセルフホストランナーへのアクセスを管理する」を参照してください。

セルフホステッド ランナー上でマルチリポジトリ バリアント分析を含むクエリを実行した場合、分析は完全にセルフホステッド ランナー上で実行されます。 新しいワークフローを作成する必要はありませんが、Visual Studio Code 拡張機能の CodeQL がコントローラー リポジトリとして使うリポジトリを指定する必要があります。 各リポジトリの分析が完了すると、結果を表示するために VS Code に送信されます。