CodeQL 分析結果をGitHubにアップロードする

CodeQL CLI を使って CodeQL データベースを分析した後、結果が含まれる SARIF ファイルが作成されます。その後は、CodeQL CLI を使って、結果を GitHub にアップロードできます。

CodeQL CLI 以外の手法を使用した場合は、他のアップロード方法を使用できます。詳しくは、「SARIF ファイルを GitHub にアップロードする」をご覧ください。

GitHub での認証用トークンを生成する

結果を GitHub にアップロードする前に、まず personal access token を生成する必要があります。「個人用アクセストークンを管理する」を参照してください。

        **Personal access token (classic)** には、必要なリポジトリに対する "Code scanning アラート" の**読み書き**アクセスが必要です。

        **Fine-grained personal access token** には、"repo" の **security_events** に対するアクセス権が必要です。

サードパーティの CI システムに CodeQL CLI をインストールしている場合は、GitHub App を使用して、GitHub に結果をアップロードすることもできます。「既存の CI システムでコードスキャンを使用する」を参照してください。

結果を GitHub にアップロードする

SARIF プロパティにアップロード用のサポートされているサイズがあり、ファイルがコードスキャンと互換性があることを確認します。詳しくは、「Code scanningの SARIF サポート」をご覧ください。
前のセクションで作成した GitHub App または personal access token を CodeQL CLI に渡す最適な方法を決定します。シークレットストアの安全な使用に関する CI システムのガイダンスを確認することをお勧めします。 CodeQL CLIは以下をサポートします。
- シークレットストアとインターフェイスに --github-auth-stdin オプションを使います (推奨)。
- 環境変数 GITHUB_TOKEN にシークレットを保存し、--github-auth-stdin オプションを含めずに CLI を実行する。
- テスト目的であれば、--github-auth-stdin コマンドラインオプションを渡し、標準入力経由で一時トークンを指定することができます。

構成の最も安全で信頼性の高い方法を決定した場合は、各 SARIF 結果ファイルで codeql github upload-results を実行し、トークンが環境変数 --github-auth-stdin で使用可能でない限り、GITHUB_TOKEN を含めます。

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-url=<URL> \
    --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-url=<URL> \

Option	必須	Usage
`--repository`		データのアップロード先となるリポジトリの OWNER/NAME を指定します。所有者は組織である必要があります。リポジトリに GitHub Advanced Security が有効になっていることが条件です。詳しくは、「リポジトリのセキュリティと分析設定を管理する」をご覧ください。
`--ref`		チェックアウトして分析した `ref` の名前を指定して、結果を正しいコードと照合できるようにします。ブランチで `refs/heads/BRANCH-NAME` を使用するか、pull request のヘッドコミットで `refs/pull/NUMBER/head` を使用するか、pull request の GitHub で生成されたマージコミットで `refs/pull/NUMBER/merge` を使用します。
`--commit`		分析したコミットの完全な SHA を指定します。
`--sarif`		読み込む SARIF ファイルを指定します。
`--github-url`		お使いの GitHub Enterprise Server インスタンスの URL を指定します。
`--github-auth-stdin`		GitHub の REST API での認証用に作成された GitHub App または personal access token を標準入力でシークレットストアから CLI に渡します。このトークンを使用して設定された `GITHUB_TOKEN` 環境変数にコマンドがアクセスできる場合、これは必要ありません。

詳しくは、「GitHubで結果をアップロード (github upload-results)」をご覧ください。

メモ

1 つのコミットに対して複数の CodeQL データベースを分析する場合、このコマンドで生成された結果セットごとに SARIF カテゴリを指定する必要があります。結果を GitHub にアップロードすると、code scanning はこのカテゴリを使ってそれぞれの言語に対する結果を別々に保存します。この操作を忘れた場合は、各アップロードで前の結果が上書きされます。詳しくは、「CodeQL クエリによるコード分析」をご覧ください。

結果を GitHub にアップロードする方法の基本的な例

次の例では、SARIF ファイル temp/example-repo-js.sarif からリポジトリ my-org/example-repo に結果をアップロードします。結果が deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 ブランチのコミット main に対するものであることを code scanning API に伝えます。この例は、GitHub の REST API での認証用に作成された GitHub App または personal access token で GITHUB_TOKEN 環境変数を使っていることを前提としています。

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-url=http://HOSTNAME \

アップロードが失敗しなければ、このコマンドからの出力はありません。コマンドプロンプトは、アップロードが完了してデータ処理が開始された時点で戻ってきます。小さなコードベースの場合、すぐに GitHub で code scanning アラートを確認できます。チェックアウトしたコードに応じて、アラートをプルリクエスト内やブランチのセキュリティタブで直接確認できます。

分析が失敗した場合に診断情報を GitHub にアップロードする

CodeQL CLI でデータベースの分析が正常に完了すると、ファイルカバレッジ、警告、エラーなどの診断情報が収集され、それを結果とともに SARIF ファイルに含めます。 SARIF ファイルを GitHub にアップロードすると、そのリポジトリの code scanning ツールの状態ページに診断情報が表示され、CodeQL がどの程度正常に動作しているかを簡単に確認し、あらゆる問題をデバッグできます。詳しくは、「コードスキャンにツールの状態ページを使用する」をご覧ください。

ただし、codeql database analyze が何らかの理由で失敗した場合は、GitHub にアップロードする SARIF ファイルがなく、そのリポジトリの code scanning ツールの状態ページに表示する診断情報がありません。これにより、ユーザーが CI システム内のログファイルにアクセスできない限り、分析のトラブルシューティングが困難になります。

分析が失敗した場合は、診断情報を GitHub にエクスポートしてアップロードするように CI ワークフローを構成することをお勧めします。これは、次の簡単なコマンドを使用して診断情報をエクスポートし、GitHub にアップロードすることで行うことができます。

分析が失敗した場合の診断情報のエクスポート

「データベースエクスポート診断」を使用して、失敗した分析用の SARIF ファイルを作成できます。次に例を示します。

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript-typescript --format=sarifv2.1.0 \
    --output=/temp/example-repo-js.sarif

この SARIF ファイルには、分析中に生成されたファイルカバレッジ情報、警告、エラーなど、失敗した分析の診断情報が含まれます。

分析が失敗した場合の診断情報のアップロード

この診断情報をツールの状態ページで使用できるようにするには、「GitHubで結果をアップロード (github upload-results)」を参考にして SARIF ファイルを GitHub にアップロードします。次に例を示します。

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-url=http://HOSTNAME \

これは、成功した分析から SARIF ファイルをアップロードするプロセスと同じです。

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

この記事で