이 버전의 GitHub Enterprise Server는 다음 날짜에 중단됩니다. 2026-04-09. 중요한 보안 문제에 대해서도 패치 릴리스가 이루어지지 않습니다. 더 뛰어난 성능, 향상된 보안, 새로운 기능을 위해 최신 버전의 GitHub Enterprise Server로 업그레이드합니다. 업그레이드에 대한 도움말은 GitHub Enterprise 지원에 문의하세요.

CodeQL 분석 결과를 GitHub 업로드

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

누가 이 기능을 사용할 수 있나요?

쓰기 권한이 있는 사용자

CodeQL은(는) 다음 리포지토리 유형에 사용할 수 있습니다.

이 기사에서

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

결과를 생성하기 위해 이외의 메서드를 CodeQL CLI 사용한 경우 다른 업로드 메서드를 사용할 수 있습니다. 자세한 내용은 GitHub에 SARIF 파일 업로드을(를) 참조하세요.

다음을 사용하여 인증을 위한 토큰 생성 GitHub

결과를 GitHub에 업로드하기 전에, 먼저 personal access token를 생성해야 합니다. 개인용 액세스 토큰 관리을(를) 참조하세요.

  •         **
        Personal access token (classic)
        ** 에는 필요한 리포지토리에 대한 "Code scanning 경고" **읽기 및 쓰기** 권한이 필요합니다.

  •         **
        Fine-grained personal access token
        ** 에는 "리포지토리" **security_events** 액세스가 필요합니다.

타사 CI 시스템에 CodeQL CLI을 설치한 경우, 결과를 GitHub App에 업로드하는 데 사용할 GitHub을(를) 사용할 수 있습니다. 사용자의 기존 CI 시스템으로 코드 검색 사용하기을(를) 참조하세요.

결과를 에 업로드

  1. SARIF 속성의 업로드 크기가 지원되고 파일이 코드 검색과 호환되었는지 확인합니다. 자세한 내용은 코드 검사에 대한 SARIF 지원을(를) 참조하세요.

  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을 포함시킵니다.

    # 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데이터를 업로드할 리포지토리의 _소유자/이름_을 지정합니다. 리포지토리가 공개 대해 사용하도록 설정된 엔터프라이즈 내 또는 계획에GitHub Advanced Security이어야 합니다. 자세한 내용은 리포지토리에 대한 보안 및 분석 설정 관리을(를) 참조하세요.
--ref결과가 올바른 코드와 매칭될 수 있도록 체크 아웃하고 분석한 ref의 이름을 지정합니다. 분기를 사용할 경우: refs/heads/BRANCH-NAME, 끌어오기 요청의 헤드 커밋을 사용할 경우 refs/pull/NUMBER/head, 또는 끌어오기 요청의 GitHub-생성 병합 커밋을 사용할 경우 refs/pull/NUMBER/merge.
--commit분석한 커밋의 전체 SHA를 지정합니다.
--sarif로드할 SARIF 파일을 지정합니다.
--github-url에 대한 URL을 지정합니다 GitHub Enterprise Server 인스턴스.
--github-auth-stdinCLI에서 GitHub App 또는 personal access token를 표준 입력을 통해 비밀 저장소로부터 전달하여 GitHub의 REST API로 인증합니다. 명령이 이 토큰을 사용하여 설정된 GITHUB_TOKEN 환경 변수에 액세스할 수 있는 경우에는 이 항목이 필요하지 않습니다.

자세한 내용은 GitHub 업로드-결과을(를) 참조하세요.

참고

단일 커밋에 대해 둘 CodeQL 이상의 데이터베이스를 분석한 경우 이 명령에서 생성된 각 결과 집합에 대해 SARIF 범주를 지정해야 합니다. 결과를 업로드할 GitHubcode scanning 때 이 범주를 사용하여 각 언어에 대한 결과를 개별적으로 저장합니다. 이 작업을 수행하지 않으면 각 업로드가 이전 결과를 덮어씁니다. 자세한 내용은 CodeQL 쿼리를 사용하여 코드 분석을(를) 참조하세요.

결과를 에 업로드하는 기본 예제 GitHub

다음은 SARIF 파일의 결과를 temp/example-repo-js.sarif리포지토리로 my-org/example-repo업로드하는 예시입니다. API에 deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 커밋에 대한 결과가 main 브랜치에서 있음을 알립니다. 이 예제에서는 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=https://HOSTNAME \

업로드에 실패하지 않는 한 이 명령의 출력은 없습니다. 명령 프롬프트는 업로드가 완료되고 데이터 처리가 시작될 때 반환됩니다. 더 작은 코드베이스에서는 code scanning 경고를 GitHub 잠시 후에 탐색할 수 있어야 합니다. 확인한 코드에 따라 풀 리퀘스트 또는 Security 브랜치 탭에서 직접 경고를 볼 수 있습니다.

분석이 실패하는 경우 GitHub에 진단 정보를 업로드합니다.

          CodeQL CLI 데이터베이스 분석이 성공적으로 완료되면 파일 검사, 경고 및 오류와 같은 진단 정보를 수집하고 결과를 포함하는 SARIF 파일에 포함합니다. SARIF 파일을 GitHub에 업로드하면 진단 정보가 리포지토리의 code scanning도구 상태 페이지에 표시되어 쉽게 CodeQL가 어떻게 작동하는지 확인하고 문제를 쉽게 디버깅할 수 있습니다. 자세한 내용은 [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page)을(를) 참조하세요.

어떠한 이유로 codeql database analyze이(가) 실패할 경우, GitHub에 업로드할 SARIF 파일이 없고, 리포지토리에 code scanning도구 상태 페이지 표시할 진단 정보도 없습니다. 따라서 사용자가 CI 시스템의 로그 파일에 액세스할 수 없는 한 분석 문제를 해결하기가 힘듭니다.

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

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

          [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-export-diagnostics)을 이용해 실패한 분석에 대한 SARIF 파일을 생성할 수 있으며, 다음을 예로 들 수 있습니다.

$ 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 업로드-결과을 사용하십시오. 예를 들어:

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 파일 업로드 프로세스와 동일합니다.