CodeQL code scanning for compiled languages

About the CodeQL analysis workflow and compiled languages

Code scanning works by running queries against one or more CodeQL databases. Each database contains a representation of the code in a single language in your repository. For the compiled languages C/C++, C#, Go, and Java, the process of populating this database involves building the code and extracting data.

The basic CodeQL analysis workflow uses the autobuild action to build your code. Alternatively, you can disable autobuild and instead specify explicit build commands to analyze only the files that are built by these custom commands.

In GitHub Enterprise Server 3.9, default setup does not support any compiled languages, so you must use advanced setup. Advanced setup generates a workflow file you can edit. The starter workflow files use autobuild to analyze compiled languages. For more information, see "Configuring advanced setup for code scanning."

For information about the languages, libraries, and frameworks that are supported in the latest version of CodeQL, see "Supported languages and frameworks" in the CodeQL documentation. For information about the system requirements for running the latest version of CodeQL, see "System requirements" in the CodeQL documentation.

About Autobuild for CodeQL

The basic CodeQL analysis workflow uses the autobuild action to build your code.

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

    - name: Autobuild
      uses: github/codeql-action/autobuild@v2

About specifying build steps manually

If autobuild fails, or you want to analyze a different set of source files from those built by the autobuild process, you'll need to remove or comment out the autobuild step in the workflow. Then uncomment the run step and manually specify the build process to use. For C/C++, C#, Go, and Java, CodeQL will analyze whatever source code is built by your specified build steps. For information on how to edit the workflow file, see "Customizing your advanced setup for code scanning."

    # Autobuild attempts to build any compiled languages.
    # - name: Autobuild
    #  uses: github/codeql-action/autobuild@v2

Specifying build commands

When manual building is enabled, uncomment the run step in the workflow and add build commands that are suitable for your repository. The 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."

Specifying build commands for multiple languages

For repositories with multiple compiled languages, you can specify language-specific build commands. For example, if your repository contains C/C++, C# and Java, you might want to provide manual build steps for one language (here Java). This specifies build steps for Java while still using autobuild for C/C++ and C#.

- if: matrix.language == 'cpp' || matrix.language == 'csharp'
  name: Autobuild
  uses: github/codeql-action/autobuild@v2
- if: matrix.language == 'java'
  name: Build Java
  run: |
    make bootstrap
    make release

For more information about the if conditional, see "Workflow syntax for GitHub Actions."

If you added manual build steps for compiled languages and code scanning is still not working on your repository, contact your site administrator.

Autobuild steps for compiled languages

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.

• Building C/C++
• Building C#
• Building Go
• Building Java and Kotlin

Building C/C++

Supported system type	System name
Operating system	Windows, macOS, and Linux
Build system	Windows: MSbuild and build scripts Linux and macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild, and build scripts

The behavior of the autobuild step varies according to the operating system that the extraction runs on.

Windows autodetection

On Windows, the autobuild step attempts to autodetect a suitable build method for C/C++ using the following approach:

1. Invoke MSBuild.exe on the solution (.sln) or project (.vcxproj) 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.
2. Invoke a script that looks like a build script—build.bat, build.cmd, and build.exe (in that order).

Linux and macOS autodetection

On Linux and macOS, the autobuild 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.

Runner requirements for C/C++

For self-hosted runners, you will likely need to install the gcc compiler, and specific projects may also require access to clang or msvc executables. You will also need to install the build system (for example msbuild, make, cmake, bazel) and utilities (such as python, perl, lex, and yacc) that your projects depend on.

Windows runners require powershell.exe to be on the PATH.

Building C#

Supported system type	System name
Operating system	Windows, macOS, and Linux
Build system	.NET and MSbuild, as well as build scripts

Windows autodetection

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.exe 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.bat, build.cmd, and build.exe (in that order).

Runner requirements for C# on Windows

For .NET Core application development on self-hosted runners, the .NET SDK is required (for dotnet).

For .NET Framework application development, you will need Microsoft Build Tools (for msbuild) and Nuget CLI (for nuget).

Windows runners require powershell.exe to be on the PATH.

Linux and macOS autodetection

1. Invoke dotnet build on the solution (.sln) or project (.csproj) file closest to the root.
2. Invoke MSbuild 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).

Runner requirements for C# on Linux and macOS

For .NET Core application development on self-hosted runners, the .NET SDK is required (for dotnet).

For .NET Framework application development, you will require Mono Runtime (to run mono, msbuild, or nuget).

Building Go

Supported system type	System name
Operating system	Windows, macOS, and Linux
Build system	Go modules, dep and Glide, as well as build scripts including Makefiles and Ninja scripts

Autodetection for Go

The autobuild process attempts to autodetect a suitable way to install the dependencies needed by a Go repository before extracting all .go files:

1. Invoke make, ninja, ./build or ./build.sh (in that order) until one of these commands succeeds and a subsequent go list ./... also succeeds, indicating that the needed dependencies have been installed.
2. If none of those commands succeeded, look for go.mod, Gopkg.toml or glide.yaml, and run go get (unless vendoring is in use), dep ensure -v or glide install respectively to try to install dependencies.
3. Finally, if configurations files for these dependency managers are not found, rearrange the repository directory structure suitable for addition to GOPATH, and use go get to install dependencies. The directory structure reverts to normal after extraction completes.
4. Extract all Go code in the repository, similar to running go build ./....

Building Java and Kotlin

Supported system type	System name
Operating system	Windows, macOS, and Linux (no restriction)
Build system	Gradle, Maven and Ant

Autodetection for Java

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.

Runner requirements for Java

If you're using self-hosted runners, the required version(s) of Java should be present:

• If the runner will be used for analyzing repositories that need a single version of Java, then the appropriate JDK version needs to be installed, and needs to be present in the PATH variable (so that java and javac can be found).

• If the runner will be used for analyzing repositories that need multiple versions of Java, then the appropriate JDK versions need to be installed, and can be specified via the toolchains.xml file. This is a configuration file, typically used by Apache Maven, that allows you to specify the location of the tools, the version of the tools, and any additional configuration that is required to use the tools. For more information, see "Guide to Using Toolchains" in the Apache Maven documentation.

The following executables will likely be required for a range of Java projects, and should be present in the PATH variable, but they will not be essential in all cases:

• mvn (Apache Maven)
• gradle (Gradle)
• ant (Apache Ant)

You will also need to install the build system (for example make, cmake, bazel) and utilities (such as python, perl, lex, and yacc) that your projects depend on.

Windows runners require powershell.exe to be on the PATH.