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

CodeQL CLIを使用して、CodeQL分析結果をGitHubにアップロードできます。

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

CodeQL CLI以外の方法を使用して結果を生成した場合は、他のアップロード方法を使用できます。 詳細については、「[SARIF ファイルを GitHub にアップロードする](/ja/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file)」を参照してください。

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

結果を GitHubにアップロードする前に、まず personal access tokenを生成する必要があります。 「[個人用アクセス トークンを管理する](/ja/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)」を参照してください。

* \*\*Personal access token (classic)\*\*が必要なリポジトリに対して"Code scanning アラート"の読み取りと書き込みアクセスを必要とします。
* **Fine-grained personal access token** には、"repo" **security\_events アクセスが** 必要です。

サード パーティの CI システムに CodeQL CLI をインストールしている場合は、 GitHub App を使用して結果を GitHubにアップロードすることもできます。 「[既存の CI システムでコード スキャンを使用する](/ja/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/use-with-existing-ci-system#generating-a-token-for-authentication-with-github)」を参照してください。

## 結果をGitHubにアップロード

1. SARIF プロパティにアップロード用のサポートされているサイズがあり、ファイルがコード スキャンと互換性があることを確認します。 詳しくは、「[Code scanningの SARIF サポート](/ja/enterprise-server@3.22/code-security/reference/code-scanning/sarif-files/sarif-support#file-compatibility)」をご覧ください。

2. 前のセクションで作成した GitHub App または personal access token を CodeQL CLIに渡す最適な方法を決定します。 シークレット ストアの安全な使用に関する CI システムのガイダンスを確認することをお勧めします。
   CodeQL CLIでは、次の機能がサポートされます。

   * シークレット ストアとインターフェイスに `--github-auth-stdin` オプションを使います (推奨)。
   * 環境変数 `GITHUB_TOKEN` にシークレットを保存し、`--github-auth-stdin` オプションを含めずに CLI を実行する。
   * テスト目的であれば、`--github-auth-stdin` コマンドライン オプションを渡し、標準入力経由で一時トークンを指定することができます。

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

   ```shell
   # 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                                                                     |                                                                                                                                                                                                            Required                                                                                                                                                                                                            | 使用方法                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <code><span style="white-space: nowrap;">--repository</span></code>        |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | データのアップロード先となるリポジトリの *OWNER/NAME* を指定します。 所有者は、エンタープライズ内の組織有効になっている必要がありますGitHub Code Security。ただし、リポジトリがパブリックである場合はこの限りではありません。 詳細については、「[リポジトリのセキュリティと分析設定を管理する](/ja/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)」を参照してください。 |
| <code><span style="white-space: nowrap;">--ref</span></code>               |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | チェックアウトして分析した `ref` の名前を指定して、結果を正しいコードと照合できるようにします。 ブランチ使用の場合: `refs/heads/BRANCH-NAME`、プル要求のヘッド コミットの場合は `refs/pull/NUMBER/head`、またはプル要求の GitHub生成されたマージ コミットの場合は、 `refs/pull/NUMBER/merge`を使用します。                                                                                                                                                                      |
| <code><span style="white-space: nowrap;">--commit</span></code>            |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | 分析したコミットの完全な SHA を指定します。                                                                                                                                                                                                                                                                                                                                                 |
| <code><span style="white-space: nowrap;">--sarif</span></code>             |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    | 読み込む SARIF ファイルを指定します。                                                                                                                                                                                                                                                                                                                                                   |
|                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                          |
| <code><span style="white-space: nowrap;">--github-url</span></code>        |                                                     <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-check" aria-label="Required" role="img"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"></path></svg>                                                    |                                                                                                                                                                                                                                                                                                                                                                          |
| お使いの GitHub Enterprise Server インスタンスの URL を指定します。                          |                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                          |
|                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                          |
| <code><span style="white-space: nowrap;">--github-auth-stdin</span></code> | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-x" aria-label="Optional" role="img"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"></path></svg> | 標準入力を使用してシークレット ストアから GitHub App の REST API を使用して認証用に作成されたpersonal access tokenまたはGitHubを CLI に渡します。 このトークンを使用して設定された `GITHUB_TOKEN` 環境変数にコマンドがアクセスできる場合、これは必要ありません。                                                                                                                                                                                                     |

詳細については、「[GitHubで結果をアップロード (github upload-results)](/ja/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/github-upload-results)」を参照してください。

> \[!NOTE]
> 1 つのコミットに対して複数の CodeQL データベースを分析した場合は、このコマンドによって生成される結果のセットごとに SARIF カテゴリを指定する必要があります。 結果を GitHubにアップロードすると、 code scanning は、このカテゴリを使用して各言語の結果を個別に格納します。 この操作を忘れた場合は、各アップロードで前の結果が上書きされます。 詳細については、「[CodeQL クエリによるコード分析](/ja/enterprise-server@3.22/code-security/tutorials/customize-code-scanning/analyze-code#running-codeql-database-analyze)」を参照してください。

### 基本的な結果アップロード方法の例 GitHub

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

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

アップロードが失敗しなければ、このコマンドからの出力はありません。 コマンドプロンプトは、アップロードが完了してデータ処理が開始された時点で戻ってきます。 小規模なコードベースでは、すぐにcode scanningでGitHubアラートを調べることができます。 チェックアウトしたコードに応じて、プル要求またはブランチの \[ **<svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-shield" aria-label="shield" role="img"><path d="M7.467.133a1.748 1.748 0 0 1 1.066 0l5.25 1.68A1.75 1.75 0 0 1 15 3.48V7c0 1.566-.32 3.182-1.303 4.682-.983 1.498-2.585 2.813-5.032 3.855a1.697 1.697 0 0 1-1.33 0c-2.447-1.042-4.049-2.357-5.032-3.855C1.32 10.182 1 8.566 1 7V3.48a1.75 1.75 0 0 1 1.217-1.667Zm.61 1.429a.25.25 0 0 0-.153 0l-5.25 1.68a.25.25 0 0 0-.174.238V7c0 1.358.275 2.666 1.057 3.86.784 1.194 2.121 2.34 4.366 3.297a.196.196 0 0 0 .154 0c2.245-.956 3.582-2.104 4.366-3.298C13.225 9.666 13.5 8.36 13.5 7V3.48a.251.251 0 0 0-.174-.237l-5.25-1.68ZM8.75 4.75v3a.75.75 0 0 1-1.5 0v-3a.75.75 0 0 1 1.5 0ZM9 10.5a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg> Security** ] タブにアラートを直接表示できます。

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

CodeQL CLIデータベースの分析が正常に完了すると、ファイル カバレッジ、警告、エラーなどの診断情報が収集され、結果と共に SARIF ファイルに含まれます。 SARIF ファイルをアップロードして GitHub すると、リポジトリの code scanningツールの状態ページ に診断情報が表示され、 CodeQL がどの程度正常に動作しているかを簡単に確認し、問題をデバッグできます。 詳細については、「[コード スキャンにツールの状態ページを使用する](/ja/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/use-the-tools-status-page-for-code-scanning)」を参照してください。

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

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

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

「[データベースエクスポート診断](/ja/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-export-diagnostics)」を使用して、失敗した分析用の SARIF ファイルを作成できます。次に例を示します。

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

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

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

この診断情報をツールの状態ページで使用できるようにするには、GitHub を使用して SARIF ファイルを[](/ja/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/github-upload-results)にアップロードします。次に例を示します。

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

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