Configuring the CodeQL workflow for compiled languages

You can configure how GitHub uses the CodeQL Analysis workflow to scan code written in compiled languages for vulnerabilities and errors.

People with write permissions to a repository can configure code scanning for the repository.

In this article

Did this doc help you?

Note: Code scanning is currently in beta and subject to change. To request access to the beta, join the waitlist.

About the CodeQL Analysis workflow and compiled languages

You enable GitHub to run code scanning for your repository by adding a GitHub Actions workflow to the repository. For CodeQL code scanning, you add the CodeQL Analysis workflow. For more information, see "Enabling code scanning for a repository."

Typically, you don't need to edit the default workflow for code scanning. However, if required, you can edit the workflow to customize some of the settings. For example, you can edit GitHub's CodeQL Analysis workflow to specify the frequency of scans, the languages or directories to scan, and what CodeQL code scanning looks for in your code. You might also need to edit the CodeQL Analysis workflow if you use a specific set of commands to compile your code or if there is more than one compiled language in your repository. For general information about configuring code scanning and editing workflow files, see "Configuring code scanning" and "Learn GitHub Actions."

About autobuild for CodeQL

For the compiled languages C/C++, C#, and Java, the autobuild step in the default CodeQL Analysis workflow attempts to build your code. In contrast to the other compiled languages, CodeQL analyzes Go without building the code.

The autobuild process only ever attempts to build one compiled language for a repository. The language automatically selected for analysis is the language with most files.

Note: If you use self-hosted runners for GitHub Actions, you may need to install additional software to use the autobuild process. Additionally, if your repository requires a specific version of a build tool, you may need to install it manually. For more information, see "Specifications for GitHub-hosted runners".

C/C++

Supported system typeSystem name
Operating systemWindows and Linux
Build systemAutoconf, CMake, qmake, Meson, Waf, SCons, and Linux Kbuild

The behavior of the autobuild step varies according to the operating system that the extraction runs on. On Windows, the step has no default actions. On Linux, this step reviews the files present in the repository to determine the build system used:

  1. Look for a build system in the root directory.
  2. If none are found, search subdirectories for a unique directory with a build system for C/C++.
  3. Run an appropriate command to configure the system.

C#

Supported system typeSystem name
Operating systemWindows and Linux
Build system.NET and MSbuild, as well as build scripts

The autobuild process attempts to autodetect a suitable build method for C# using the following approach:

  1. Invoke dotnet build on the solution (.sln) or project (.csproj) file closest to the root.
  2. Invoke MSbuild (Linux) or MSBuild.exe (Windows) on the solution or project file closest to the root. If autobuild detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them.
  3. Invoke a script that looks like a build script—build and build.sh (in that order, for Linux) or build.bat, build.cmd, and build.exe (in that order, for Windows).

Java

Supported system typeSystem name
Operating systemWindows, macOS and Linux (no restriction)
Build systemGradle, Maven and Ant

The autobuild process tries to determine the build system for Java codebases by applying this strategy:

  1. Search for a build file in the root directory. Check for Gradle then Maven then Ant build files.
  2. Run the first build file found. If both Gradle and Maven files are present, the Gradle file is used.
  3. Otherwise, search for build files in direct subdirectories of the root directory. If only one subdirectory contains build files, run the first file identified in that subdirectory (using the same preference as for 1). If more than one subdirectory contains build files, report an error.

Adding build steps for a compiled language

If the C/C++, C#, or Java code in your repository has a non-standard build process or if it's written in more than one compiled language, autobuild may fail. You will need to remove the autobuild step from the workflow, and manually add build steps. For information about editing the workflow, see "Configuring code scanning."

After removing the autobuild step, uncomment the run step and add build commands that are suitable for your repository. The workflow run step runs command-line programs using the operating system's shell. You can modify these commands and add more commands to customize the build process.

- run: |
  make bootstrap
  make release

For more information about the run keyword, see "Workflow syntax for GitHub Actions."

You can also use a build matrix to update the workflow to build more than one compiled language, if this is the appropriate approach for your system and doesn't cause conflicts. For more information, see "Managing complex workflows."

For example, the workflow below runs one job for C/C++ analysis, and another job for Java analysis.


name: "CodeQL"

on:
  push:
    branches: [main, ]
  pull_request:
    branches: [main]

jobs:
  CodeQL-Build:

    strategy:
      fail-fast: false
      matrix:
        language: ['cpp', 'java']
        
    # CodeQL runs on ubuntu-latest, windows-latest, and macos-latest
    runs-on: ubuntu-latest

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

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v1
      with:
        languages: ${{ matrix.language }}

    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
    # If this step fails, then you should remove it and run the build manually.
    - name: Autobuild
      uses: github/codeql-action/autobuild@v1

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v1

For more tips and tricks about why autobuild won't build your code, see "Troubleshooting code scanning".

If you added manual build steps for compiled languages or used a build matrix and code scanning is still not working on your repository, contact GitHub Support or GitHub Premium Support.

Did this doc help you?