# CodeQL 분석 결과를 GitHub 업로드

CodeQL CLI를 사용하여 분석 결과를 CodeQL에 업로드할 수 있습니다 GitHub.

데이터베이스를 CodeQL 사용하여 CodeQL CLI분석한 후에는 결과가 포함된 SARIF 파일이 생성됩니다. 그런 다음, CodeQL CLI를 사용하여 결과를 GitHub에 업로드할 수 있습니다.

결과를 생성하기 위해 이외의 메서드를 CodeQL CLI 사용한 경우 다른 업로드 메서드를 사용할 수 있습니다. 자세한 내용은 [GitHub에 SARIF 파일 업로드](/ko/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를 생성해야 합니다.
[개인용 액세스 토큰 관리](/ko/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** 에는 "리포지토리" **security\_events** 액세스가 필요합니다.

제3자 CI 시스템에 CodeQL CLI을 설치한 경우, 결과를 GitHub App에 업로드하는 데 GitHub를 사용할 수 있습니다.
[사용자의 기존 CI 시스템으로 코드 검색 사용하기](/ko/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)을(를) 참조하세요.

## 결과를 <c0>에 업로드

1. SARIF 속성의 업로드 크기가 지원되고 파일이 코드 검색과 호환되었는지 확인합니다. 자세한 내용은 [코드 검사에 대한 SARIF 지원](/ko/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. CI 서버에 대한 가장 안전하고 신뢰할 수 있는 방법을 결정한 경우 `codeql github upload-results` 환경 변수에서 토큰이 제공되지 않는 한 각 SARIF 결과 파일에서 `--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                                                                     |                                                                                                                                                                                                               필수                                                                                                                                                                                                               | 사용량                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <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>                                                    | 데이터를 업로드할 리포지토리의 \_소유자/이름\_을 지정합니다. 소유자는 기업 내 조직에서GitHub Code Security 가 리포지토리에 활성화된 경우, . 자세한 내용은 [리포지토리에 대한 보안 및 분석 설정 관리](/ko/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>                                                    | 에 대한 URL을 지정합니다 GitHub Enterprise Server 인스턴스.                                                                                                                                                                                                                                                                                     |
|                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                    |
| <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> | CLI에서 GitHub App 또는 personal access token를 표준 입력을 통해 비밀 저장소로부터 전달하여 GitHub의 REST API로 인증합니다. 명령이 이 토큰을 사용하여 설정된 `GITHUB_TOKEN` 환경 변수에 액세스할 수 있는 경우에는 이 항목이 필요하지 않습니다.                                                                                                                                                              |

자세한 내용은 [GitHub 업로드-결과](/ko/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/github-upload-results)을(를) 참조하세요.

> \[!NOTE]
> 단일 커밋에 대해 둘 CodeQL 이상의 데이터베이스를 분석한 경우 이 명령에서 생성된 각 결과 집합에 대해 SARIF 범주를 지정해야 합니다. 결과를 업로드할 GitHubcode scanning 때 이 범주를 사용하여 각 언어에 대한 결과를 개별적으로 저장합니다. 이 작업을 수행하지 않으면 각 업로드가 이전 결과를 덮어씁니다. 자세한 내용은 [CodeQL 쿼리를 사용하여 코드 분석](/ko/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`업로드하는 예시입니다. API에 code scanning 커밋에 대한 결과가 `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` 브랜치에서 있음을 알립니다. 이 예제에서는 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가 어떻게 작동하는지 확인하고 문제를 쉽게 디버깅할 수 있습니다. 자세한 내용은 [코드 검색에 도구 상태 페이지 사용](/ko/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 시스템의 로그 파일에 액세스할 수 없는 한 분석 문제를 해결하기가 힘듭니다.

분석이 실패할 때 진단 정보를 내보내고 업로드하도록 CI 워크플로를 GitHub 구성하는 것이 좋습니다. 다음 간단한 명령을 사용하여 진단 정보를 내보내고 업로드할 GitHub수 있습니다.

### 분석이 실패할 경우 진단 정보 내보내기

[데이터베이스 내보내기 진단](/ko/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 파일에는 분석 중 생성된 파일 적용 범위 정보, 경고 및 오류를 포함하여 실패한 분석에 대한 진단 정보가 포함됩니다.

### 분석이 실패 시 진단 정보 업로드하기

SARIF 파일을 도구 상태 페이지에 업로드하여 GitHub에서 이 진단 정보를 사용할 수 있게 [GitHub 업로드-결과](/ko/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 파일 업로드 프로세스와 동일합니다.