Skip to main content

此版本的 GitHub Enterprise 将停止服务 2022-06-03. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

Troubleshooting the CodeQL workflow

If you're having problems with 代码扫描, you can troubleshoot by using these tips for resolving issues.

代码扫描 适用于启用了 GitHub Advanced Security 的组织拥有的仓库。 更多信息请参阅“关于 GitHub Advanced Security”。

Note: This article describes the features available with the version of the CodeQL action and associated CodeQL CLI bundle included in the initial release of this version of GitHub Enterprise Server. If your enterprise uses a more recent version of the CodeQL action, see the GitHub Enterprise Cloud article for information on the latest features. For information on using the latest version, see "Configuring code scanning for your appliance."

Producing detailed logs for debugging

To produce more detailed logging output, you can enable step debug logging. For more information, see "Enabling debug logging."

Automatic build for a compiled language fails

If an automatic build of code for a compiled language within your project fails, try the following troubleshooting steps.

  • Remove the autobuild step from your 代码扫描 workflow and add specific build steps. For information about editing the workflow, see "Configuring 代码扫描." For more information about replacing the autobuild step, see "Configuring the CodeQL workflow for compiled languages."

  • If your workflow doesn't explicitly specify the languages to analyze, CodeQL implicitly detects the supported languages in your code base. In this configuration, out of the compiled languages C/C++, C#, and Java, CodeQL only analyzes the language with the most source files. Edit the workflow and add a matrix specifying the languages you want to analyze. The default CodeQL analysis workflow uses such a matrix.

    The following extracts from a workflow show how you can use a matrix within the job strategy to specify languages, and then reference each language within the "Initialize CodeQL" step:

    jobs:
      analyze:
        ...
        strategy:
          fail-fast: false
          matrix:
            language: ['csharp', 'cpp', 'javascript']
    
        steps:
        ...
          - name: Initialize CodeQL
            uses: github/codeql-action/init@v1
            with:
              languages: ${{ matrix.language }}
    

    For more information about editing the workflow, see "Configuring code scanning."

No code found during the build

If your workflow fails with an error No source code was seen during the build or The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32, this indicates that CodeQL was unable to monitor your code. Several reasons can explain such a failure:

  1. The repository may not contain source code that is written in languages supported by CodeQL. Check the list of supported languages and, if this is the case, remove the CodeQL workflow. For more information, see "About code scanning with CodeQL

  2. Automatic language detection identified a supported language, but there is no analyzable code of that language in the repository. A typical example is when our language detection service finds a file associated with a particular programming language like a .h, or .gyp file, but no corresponding executable code is present in the repository. To solve the problem, you can manually define the languages you want to analyze by updating the list of languages in the language matrix. For example, the following configuration will analyze only Go, and JavaScript.

    strategy:
      fail-fast: false
      matrix:
        # Override automatic language detection by changing the list below.
        # Supported options are listed in a comment in the default workflow.
        language: ['go', 'javascript']
    

    For more information, see the workflow extract in "Automatic build for a compiled language fails" above.

  3. Your 代码扫描 workflow is analyzing a compiled language (C, C++, C#, or Java), but the code was not compiled. By default, the CodeQL analysis workflow contains an autobuild step, however, this step represents a best effort process, and may not succeed in building your code, depending on your specific build environment. Compilation may also fail if you have removed the autobuild step and did not include build steps manually. For more information about specifying build steps, see "Configuring the CodeQL workflow for compiled languages."

  4. Your workflow is analyzing a compiled language (C, C++, C#, or Java), but portions of your build are cached to improve performance (most likely to occur with build systems like Gradle or Bazel). Since CodeQL observes the activity of the compiler to understand the data flows in a repository, CodeQL requires a complete build to take place in order to perform analysis.

  5. Your workflow is analyzing a compiled language (C, C++, C#, or Java), but compilation does not occur between the init and analyze steps in the workflow. CodeQL requires that your build happens in between these two steps in order to observe the activity of the compiler and perform analysis.

  6. Your compiled code (in C, C++, C#, or Java) was compiled successfully, but CodeQL was unable to detect the compiler invocations. The most common causes are:

    • Running your build process in a separate container to CodeQL. For more information, see "Running CodeQL code scanning in a container."
    • Building using a distributed build system external to GitHub Actions, using a daemon process.
    • CodeQL isn't aware of the specific compiler you are using.

    For .NET Framework projects, and for C# projects using either dotnet build or msbuild, you should specify /p:UseSharedCompilation=false in your workflow's run step, when you build your code.

    For example, the following configuration for C# will pass the flag during the first build step.

    - run: |
        dotnet build /p:UseSharedCompilation=false
    

    If you encounter another problem with your specific compiler or configuration, contact 您的网站管理员.

For more information about specifying build steps, see "Configuring the CodeQL workflow for compiled languages."

Portions of my repository were not analyzed using autobuild

The CodeQL autobuild feature uses heuristics to build the code in a repository, however, sometimes this approach results in incomplete analysis of a repository. For example, when multiple build.sh commands exist in a single repository, the analysis may not complete since the autobuild step will only execute one of the commands. The solution is to replace the autobuild step with build steps which build all of the source code which you wish to analyze. For more information, see "Configuring the CodeQL workflow for compiled languages."

The build takes too long

If your build with CodeQL analysis takes too long to run, there are several approaches you can try to reduce the build time.

Increase the memory or cores

If you use self-hosted runners to run CodeQL analysis, you can increase the memory or the number of cores on those runners.

Use matrix builds to parallelize the analysis

The default CodeQL 分析工作流程 uses a matrix of languages, which causes the analysis of each language to run in parallel. If you have specified the languages you want to analyze directly in the "Initialize CodeQL" step, analysis of each language will happen sequentially. To speed up analysis of multiple languages, modify your workflow to use a matrix. For more information, see the workflow extract in "Automatic build for a compiled language fails" above.

Reduce the amount of code being analyzed in a single workflow

Analysis time is typically proportional to the amount of code being analyzed. You can reduce the analysis time by reducing the amount of code being analyzed at once, for example, by excluding test code, or breaking analysis into multiple workflows that analyze only a subset of your code at a time.

对于 Java、C、C++ 和 C# 等编译语言,CodeQL 分析在工作流程运行过程中构建的所有代码。 要限制要分析的代码量,请通过在 run 块中指定自己的构建步骤,仅构建您要分析的代码。 您可以通过对 pull_requestpush 事件使用 pathspaths-ignore 过滤器来组合指定自己的构建步骤,以确保工作流程仅在特定代码发生更改时运行。 更多信息请参阅“GitHub Actions 的工作流程语法”。

对于 Go、JavaScript、Python 和 TypeScript 等语言, CodeQL 分析而不编译源代码,您可以指定其他配置选项来限制要分析的代码量。 更多信息请参阅“指定要扫描的目录”。

If you split your analysis into multiple workflows as described above, we still recommend that you have at least one workflow which runs on a schedule which analyzes all of the code in your repository. Because CodeQL analyzes data flows between components, some complex security behaviors may only be detected on a complete build.

Run only during a schedule event

If your analysis is still too slow to be run during push or pull_request events, then you may want to only trigger analysis on the schedule event. For more information, see "Events."

Check which query suites the workflow runs

By default, there are three main query suites available for each language. If you have optimized the CodeQL database build and the process is still too long, you could reduce the number of queries you run. The default query suite is run automatically; it contains the fastest security queries with the lowest rates of false positive results.

You may be running extra queries or query suites in addition to the default queries. Check whether the workflow defines an additional query suite or additional queries to run using the queries element. You can experiment with disabling the additional query suite or queries. For more information, see "Configuring 代码扫描."

Error: "Server error"

If the run of a workflow for 代码扫描 fails due to a server error, try running the workflow again. If the problem persists, contact 您的网站管理员.

Error: "Out of disk" or "Out of memory"

On very large projects, CodeQL may run out of disk or memory on the runner. If you encounter this issue, try increasing the memory on the runner.

Error: "is not a .ql file, .qls file, a directory, or a query pack specification"

You will see this error if CodeQL is unable to find the named query, query suite, or query pack at the location requested in the workflow. There are two common reasons for this error.

  • There is a typo in the workflow.
  • A resource the workflow refers to by path was renamed, deleted, or moved to a new location.

After verifying the location of the resource, you can update the workflow to specify the correct location. If you run additional queries in Go analysis, you may have been affected by the relocation of the source files. For more information, see Relocation announcement: github/codeql-go moving into github/codeql in the github/codeql-go repository.

Warning: "git checkout HEAD^2 is no longer necessary"

If you're using an old CodeQL workflow you may get the following warning in the output from the "Initialize CodeQL" action:

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer 
necessary. Please remove this step as Code Scanning recommends analyzing the merge 
commit for best results.

Fix this by removing the following lines from the CodeQL workflow. These lines were included in the steps section of the Analyze job in initial versions of the CodeQL workflow.

        with:
          # We must fetch at least the immediate parents so that if this is
          # a pull request then we can checkout the head.
          fetch-depth: 2

      # If this run was triggered by a pull request event, then checkout
      # the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

The revised steps section of the workflow will look like this:

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v1

      ...

For more information about editing the CodeQL workflow file, see "Configuring 代码扫描."