Note
Your site administrator must enable code scanning before you can use this feature. If you want to use GitHub Actions to scan your code, the site administrator must also enable GitHub Actions and set up the infrastructure required. For more information, see "Configuring code scanning for your appliance."
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, Java, Kotlin, and Swift, the process of populating this database involves building the code and extracting data.
If you enable default setup, the autobuild
action will be used to build your code, as part of your automatically configured CodeQL analysis workflow. If you enable advanced setup, the basic CodeQL analysis workflow uses autobuild
. Alternatively, you can disable autobuild
and instead specify explicit build commands to analyze only the files that are built by these custom commands.
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 CodeQL action uses autobuild
to analyze compiled languages in the following cases.
- Default setup is enabled.
- Advanced setup is enabled and the workflow has an Autobuild step for the language using the
autobuild
action (github/codeql-action/autobuild@v2
).
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
You can only specify manual build steps if you have enabled advanced setup, see "Configuring advanced setup for code scanning."
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, Java, Kotlin, and Swift, 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. For self-hosted runners, you should install dependencies directly in the runners themselves. We provide examples of common dependencies for C/C++, C#, and Java in each of the autobuild
sections of this article for those languages. For more information, see "About self-hosted runners."
Note
If your workflow uses a language
matrix, autobuild
attempts to build each of the compiled languages listed in the matrix. Without a matrix autobuild
attempts to build the supported compiled language that has the most source files in the repository. With the exception of Go, analysis of other compiled languages in your repository will fail unless you supply explicit build commands.
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:
- Invoke
MSBuild.exe
on the solution (.sln
) or project (.vcxproj
) file closest to the root. Ifautobuild
detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them. - 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:
- Look for a build system in the root directory.
- If none are found, search subdirectories for a unique directory with a build system for C/C++.
- Run an appropriate command to configure the system.
Runner requirements for C/C++
On Ubuntu Linux runners, autobuild
may try to automatically install dependencies required by the detected configuration and build steps. By default, this behavior is enabled on GitHub-hosted runners and disabled on self-hosted runners. You can enable or disable this feature explicitly by setting CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES
to true
or false
in the environment. For more information about defining environment variables, see "Store information in variables."
For self-hosted runners, unless automatic installation of dependencies is enabled, 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.
If you enable automatic installation of dependencies, you must ensure that the runner is using Ubuntu and that it can run sudo apt-get
without requiring a password.
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 |
C# compiler flags injected by CodeQL
Note
The following compiler flags only apply if you're using build mode manual
.
The CodeQL tracer enables the extraction of all compiled languages by intercepting build processes and forwarding information to the relevant CodeQL language extractors. The tracer injects certain flags into the C# compiler invocation to ensure every component is built and included in the CodeQL database, which may cause your C# code to build in a different way to what you expect during CodeQL analysis.
/p:MvcBuildViews=true
When this option is set to true
, the views in ASP.NET model-view-controller (MVC) projects are precompiled as part of the build process, which can help to catch errors and improve performance. The tracer injects this flag to make sure CodeQL finds and highlights security issues that may involve dataflow through the code generated from these views. For more information, see "Adding a View to an MVC Application" in Microsoft Learn.
/p:UseSharedCompilation=false
Setting this option to false
disables the use of the shared compilation feature, which may result in slower build times. When /p:UseSharedCompilation=false
is not specified, msbuild
starts a compiler server process, and all the compilation will be done by that single process. However, the CodeQL tracer depends on inspecting the arguments of newly created processes.
/p:EmitCompilerGeneratedFiles=true
Setting this option to true
will emit compiler-generated files during the build process. This option causes the compiler to generate additional source files that are used to support features such as improved regular expression support, serialization, and web application view generation. These generated artifacts are typically not written to disk by the compiler, but setting the option to true
forces writing the files to disk, and so the extractor can process the files.
For some legacy projects, and projects that use .sqlproj
files, you may see that the injected /p:EmitCompilerGeneratedFiles=true
property causes unexpected issues with msbuild
. For information about troubleshooting this, see "C# compiler unexpectedly failing."
Windows autodetection
The autobuild
process attempts to autodetect a suitable build method for C# using the following approach:
- Invoke
dotnet build
on the solution (.sln
) or project (.csproj
) file closest to the root. - Invoke
MSBuild.exe
on the solution or project file closest to the root. Ifautobuild
detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them. - Invoke a script that looks like a build script—
build.bat
,build.cmd
, andbuild.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
- Invoke
dotnet build
on the solution (.sln
) or project (.csproj
) file closest to the root. - Invoke
MSbuild
on the solution or project file closest to the root. Ifautobuild
detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them. - Invoke a script that looks like a build script—
build
andbuild.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:
- Invoke
make
,ninja
,./build
or./build.sh
(in that order) until one of these commands succeeds and a subsequentgo list ./...
also succeeds, indicating that the needed dependencies have been installed. - If none of those commands succeeded, look for
go.mod
,Gopkg.toml
orglide.yaml
, and rungo get
(unless vendoring is in use),dep ensure -v
orglide install
respectively to try to install dependencies. - Finally, if configurations files for these dependency managers are not found, rearrange the repository directory structure suitable for addition to
GOPATH
, and usego get
to install dependencies. The directory structure reverts to normal after extraction completes. - Extract all Go code in the repository, similar to running
go build ./...
.
Note
If you use default setup, it will look for a go.mod
file to automatically install a compatible version of the Go language. If you're using a self-hosted runner with default setup that doesn't have internet access, you can manually install a compatible version of Go.
Extractor options for Go
By default, test code (code in files ending in _test.go
) is not analyzed. You can override this with the option --extractor-option extract_tests=true
when using the CodeQL CLI, or by setting the environment variable CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS
to true
.
Additionally, vendor
directories are excluded from CodeQL Go analysis by default. You can override this by passing the --extractor-option extract_vendor_dirs=true
option when using the CodeQL CLI, or by setting the environment variable CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS
to true
.
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:
- Search for a build file in the root directory. Check for Gradle then Maven then Ant build files.
- Run the first build file found. If both Gradle and Maven files are present, the Gradle file is used.
- 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
andjavac
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
.
Building Swift
Supported system type | System name |
---|---|
Operating system | macOS |
Build system | Xcode |
The autobuild
process tries to build the biggest target from an Xcode project or workspace.
Code scanning of Swift code uses macOS runners by default.
Code scanning of Swift code is not supported for runners that are part of an Actions Runner Controller (ARC), because ARC runners only use Linux and Swift requires macOS runners. However, you can have a mixture of both ARC runners and self-hosted macOS runners. For more information, see "About Actions Runner Controller."
Customizing Swift compilation in a CodeQL analysis workflow
xcodebuild
and swift build
are both supported for Swift builds. We recommend only targeting one architecture during the build. For example, ARCH=arm64
for xcodebuild
, or --arch arm64
for swift build
.
You can pass the archive
and test
options to xcodebuild
. However, the standard xcodebuild
command is recommended as it should be the fastest, and should be all that CodeQL requires for a successful scan.
For Swift analysis, you must always explicitly install dependencies managed via CocoaPods or Carthage before generating the CodeQL database.