注：站点管理员必须为 your GitHub Enterprise Server instance 启用 代码扫描，然后您才可使用此功能。 更多信息请参阅“为设备配置 代码扫描”。
Once you've made the CodeQL CLI available to servers in your CI system, and ensured that they can authenticate with GitHub Enterprise Server, you're ready to generate data.
You use three different commands to generate results and upload them to GitHub Enterprise Server:
database createto create a CodeQL database to represent the hierarchical structure of a supported programming language in the repository.
database analyzeto run queries to analyze the CodeQL database and summarize the results in a SARIF file.
github upload-resultsto upload the resulting SARIF file to GitHub Enterprise Server where the results are matched to a branch or pull request and displayed as 代码扫描 alerts.
You can display the command-line help for any command using the
注：上传 SARIF 数据以显示为 GitHub Enterprise Server 中的 代码扫描 结果适用于启用了 GitHub Advanced Security 的组织拥有的仓库。 更多信息请参阅“管理仓库的安全和分析设置”。
Check out the code that you want to analyze:
- For a branch, check out the head of the branch that you want to analyze.
- For a pull request, check out either the head commit of the pull request, or check out a GitHub-generated merge commit of the pull request.
Set up the environment for the codebase, making sure that any dependencies are available. For more information, see Creating databases for non-compiled languages and Creating databases for compiled languages in the documentation for the CodeQL CLI.
Find the build command, if any, for the codebase. Typically this is available in a configuration file in the CI system.
codeql database createfrom the checkout root of your repository and build the codebase.
codeql database create <database> --command<build> --language=<language-identifier>
Note: If you use a containerized build, you need to run the CodeQL CLI inside the container where your build task takes place.
|Specify the name and location of a directory to create for the CodeQL database. The command will fail if you try to overwrite an existing directory. If you also specify |
|Specify the identifier for the language to create a database for, one of: |
|Recommended. Use to specify the build command or script that invokes the build process for the codebase. Commands are run from the current folder or, where it is defined, from |
|Optional. Use if you run the CLI outside the checkout root of the repository. By default, the |
For more information, see Creating CodeQL databases in the documentation for the CodeQL CLI.
This example creates a CodeQL database for the repository checked out at
- Create a CodeQL database (see above).
codeql database analyzeon the database and specify which queries to use.
codeql database analyze <database> --format=<format> \ --output=<output> <queries>
|Specify the path for the directory that contains the CodeQL database to analyze.|
|Specify CodeQL packs or queries to run. To run the standard queries used for 代码扫描, omit this parameter. To see the other query suites included in the CodeQL CLI bundle, look in |
|Specify the format for the results file generated by the command. For upload to GitHub this should be: |
|Specify where to save the SARIF results file.|
|Optional. Use if you want to use more than one thread to run queries. The default value is |
|Optional. Use to get more detailed information about the analysis process.|
For more information, see Analyzing databases with the CodeQL CLI in the documentation for the CodeQL CLI.
This example analyzes a CodeQL database stored at
/codeql-dbs/example-repo and saves the results as a SARIF file:
SARIF upload supports a maximum of 5000 results per upload. 超过此限制的任何结果均被忽略。 如果工具产生太多结果，则应更新配置，以专注于最重要的规则或查询的结果。
For each upload, SARIF upload supports a maximum size of 10 MB for the
gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.
Before you can upload results to GitHub Enterprise Server, you must determine the best way to pass the GitHub 应用程序 or personal access token you created earlier to the CodeQL CLI (see Installing CodeQL CLI in your CI system). We recommend that you review your CI system's guidance on the secure use of a secret store. The CodeQL CLI supports:
- Passing the token to the CLI via standard input using the
- Saving the secret in the environment variable
GITHUB_TOKENand running the CLI without including the
When you have decided on the most secure and reliable method for your CI server, run
codeql github upload-results on each SARIF results file and include
--github-auth-stdin unless the token is available in the environment variable
echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \ --ref=<ref> --commit=<commit> --sarif=<file> \ --github-url=<URL> --github-auth-stdin
|Specify the OWNER/NAME of the repository to upload data to. The owner must be an organization within an enterprise that has a license for GitHub Advanced Security and GitHub Advanced Security must be enabled for the repository. For more information, see "Managing security and analysis settings for your repository."|
|Specify the name of the |
|Specify the full SHA of the commit you analyzed.|
|Specify the SARIF file to load.|
|Specify the URL for GitHub Enterprise Server.|
|Optional. Use to pass the CLI the GitHub 应用程序 or personal access token created for authentication with GitHub's REST API via standard input. This is not needed if the command has access to a |
For more information, see github upload-results in the documentation for the CodeQL CLI.
This example uploads results from the SARIF file
temp/example-repo-js.sarif to the repository
my-org/example-repo. It tells the 代码扫描 API that the results are for the commit
deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 on the
$ echo $UPLOAD_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://github.example.com \ --github-auth-stdin
There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the 代码扫描 alerts in GitHub Enterprise Server shortly afterward. You can see alerts directly in the pull request or on the Security tab for branches, depending on the code you checked out. For more information, see "Triaging 代码扫描 alerts in pull requests" and "Managing 代码扫描 alerts for your repository."