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, and Swift, the process of populating this database often involves building the code and extracting data.
When you enable code scanning, both default and advanced setup generate a CodeQL database for analysis using the simplest method available. For Java, the CodeQL database is generated directly from the codebase without requiring a build (
none
build mode). For other compiled languages, CodeQL builds the codebase using the
autobuild
build mode. Alternatively, you can use the
manual
build mode to specify explicit build commands to analyze only the files that are built by these custom commands.
Note:
The option to analyze a compiled language without building it using CodeQL is currently in beta and subject to change. During the beta, this option is supported only for Java codebases.
The CodeQL action supports three different build modes for compiled languages:
none
- the CodeQL database is created directly from the codebase without building the codebase (supported for all interpreted languages, and additionally supported in beta for Java).
autobuild
- CodeQL detects the most likely build method and uses this to attempt to build the codebase and create a database for analysis (supported for all compiled languages).
manual
- you define the build steps to use for the codebase in the workflow (supported for all compiled languages).
When you are setting up code scanning for the first time, or across multiple repositories, it's best to use default setup. Default setup uses the simplest method available to generate a CodeQL database and analyze your code, so that you can start fixing alerts as soon as possible. Once you have resolved the initial alerts, you may want to switch to advanced setup with a manual build process for high risk repositories.
For repositories with multiple compiled languages, you can use different build modes for different languages. For example, if your repository contains C/C++, C# and Java, you might want to provide manual build steps for one language (here C/C++). This workflow specifies a different build mode for each language.
strategy:
matrix:
include:
-
language:
c-cpp
build-mode:
manual
-
language:
csharp
build-mode:
autobuild
-
language:
java-kotlin
build-mode:
none
steps:
-
name:
Checkout
repository
uses:
actions/checkout@v4
-
name:
Initialize
CodeQL
uses:
github/codeql-action/init@v3
with:
languages:
${{
matrix.language
}}
-
if:
${{
matrix.build-mode
==
'manual'
}}
name:
Build
C
and
C++
code
run:
|
echo 'If you are using a "manual" build mode for one or more of the' \
'languages you are analyzing, replace this with the commands to build' \
'your code, for example:'
echo ' make bootstrap'
echo ' make release'
exit 1
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.
CodeQL creates a Java database without requiring a build when one or both of the following conditions is true:
-
build-mode
is set to
none
.
- Default setup is configured and Java code (but not Kotlin code) was present when CodeQL was enabled.
CodeQL will attempt to run Gradle or Maven first in order to extract accurate dependency information (but not to invoke a build), before creating a database from all Java files present.
You can read about the system requirements to run Maven or Gradle, and the rules for selecting between them, in "
Building Java and Kotlin
". If you're creating a Java database without a build, these are the same, but note that multiple root Maven or Gradle scripts are allowed. Every root Maven or Gradle project file (a build script without any build script present in an ancestor directory) is queried for dependency information, and more recent dependency versions are preferred if there is a clash.
Creating a CodeQL Java database without a build may produce less accurate results than using
autobuild
or manual build steps if:
- Gradle or Maven build scripts cannot be queried for dependency information, and dependency guesses (based on Java package names) are inaccurate.
- The analyzed code includes code that was generated during the build process.
To use
autobuild
or manual build steps, you can use advanced setup.
If
build-mode
is set to
none
and Kotlin code is found in the repository, it will not be analyzed and a warning will be produced. See "
Building Java and Kotlin
".
The CodeQL action uses
autobuild
to analyze compiled languages in the following cases.
- Default setup is enabled and the language does not support
none
build (beta release supported for Java).
- Advanced setup is enabled and the workflow specifies
build-mode: autobuild
.
- Advanced setup is enabled and the workflow has an Autobuild step for the language using the
autobuild
action (
github/codeql-action/autobuild@v3
).
name:
Analyze
strategy:
matrix:
include:
-
language:
c-cpp
build-mode:
autobuild
-
language:
go
build-mode:
autobuild
steps:
-
uses:
github/codeql-action/init@v3
with:
languages:
${{
matrix.language
}}
build-mode:
${{
matrix.build-mode
}}
-
name:
Initialize
CodeQL
uses:
github/codeql-action/init@v3
with:
languages:
${{
matrix.language
}}
-
name:
Autobuild
uses:
github/codeql-action/autobuild@v3
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 do the following:
- If your workflow specifies a build mode for the language, change the build mode to
manual
.
- If your workflow contains an
autobuild
step, 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, 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
."
Update your workflow to define the
build-mode
as
manual
.
-
name:
Initialize
CodeQL
-
uses:
github/codeql-action/init@v3
with:
languages:
${{
matrix.language
}}
build-mode:
manual
-
uses:
github/codeql-action/analyze@v3
with:
category:
"/language:$
{{ matrix.language }}
"
Alternatively, update your workflow to comment out the "Autobuild" step.
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
."
If you added manual build steps for compiled languages and code scanning is still not working on your repository, contact us through the
GitHub Support portal
.
GitHub-hosted runners are always run with the software required by
autobuild
. 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.
CodeQL supports build modes
autobuild
or
manual
for C/C++ code.
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.
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.
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.
- Invoke a script that looks like a build script?
build.bat
,
build.cmd
,
and build.exe
(in that order).
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.
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 "
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
.
CodeQL supports build modes
autobuild
or
manual
for C# code.
Supported system type
| System name
|
---|
Operating system
| Windows, macOS, 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:
- 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.
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.
- Invoke a script that looks like a build script?
build.bat
,
build.cmd
, and
build.exe
(in that order).
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
.
- 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.
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.
- Invoke a script that looks like a build script?
build
and
build.sh
(in that order).
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
).
CodeQL supports build modes
autobuild
or
manual
for Go code.
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
|
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 subsequent
go list ./...
also succeeds, indicating that the needed dependencies have been installed.
- 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.
- 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.
- 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.
CodeQL supports the following build modes.
- Java:
none
,
autobuild
, or
manual
- Kotlin:
autobuild
or
manual
When you first enable default setup for a repository, if only Java code is detected then the build mode is set to
none
. If Kotlin or a combination of Java and Kotlin code is detected, then the build mode is set to
autobuild
.
If you later add Kotlin code to a repository that uses the
none
build mode, CodeQL analysis reports a warning message explaining that Kotlin is not supported. You will need to disable default setup and re-enable it. When you re-enable default setup, the build mode will change to
autobuild
so that both languages can be analyzed. Alternatively, you can change to an advanced setup. For more information, see "
Warning: Detected X Kotlin files in your project that could not be processed without a build
."
Supported system type
| System name
|
---|
Operating system
| Windows, macOS, and Linux (no restriction)
|
Build system
| Gradle, Maven and Ant
|
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.
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
.
CodeQL supports build modes
autobuild
or
manual
for Swift code.
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.
Notes:
- CodeQL analysis for Swift is currently in beta. During the beta, analysis of Swift code, and the accompanying documentation, will not be as comprehensive as for other languages.
Code scanning of Swift code uses macOS runners by default. Since GitHub-hosted macOS runners are more expensive than Linux and Windows runners, we recommend that you build only the code that you want to analyze. For more information about pricing for GitHub-hosted runners, see "
About billing for GitHub Actions
."
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
."
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.