Preparing your code for CodeQL analysis

About preparing your code for analysis

Before you analyze your code using CodeQL, you need to create a CodeQL database containing all the data required to run queries on your code. You can create CodeQL databases yourself using the CodeQL CLI.

CodeQL analysis relies on extracting relational data from your code, and using it to build a CodeQL database. CodeQL databases contain all of the important information about a codebase, which can be analyzed by executing CodeQL queries against it.

Before you generate a CodeQL database, you need to:

1. Install and set up the CodeQL CLI. For more information, see Setting up the CodeQL CLI.
2. Check out the code that you want to analyze:
   • For a branch, check out the head of the branch that you want to analyze.
   • For a pull request, check out either the head commit of the pull request, or check out a GitHub-generated merge commit of the pull request.
3. Set up the environment for the codebase, making sure that any dependencies are available.
4. For the best results with compiled languages, find the build command, if any, for the codebase. Typically this is available in a configuration file in the CI system.

Once the codebase is ready, you can run codeql database create to create the database. For more information, see Creating databases for non-compiled languages and Creating databases for compiled languages.

Running codeql database create

CodeQL databases are created by running the following command from the checkout root of your project:

codeql database create <database> --language=<language-identifier>

You must specify:

• <database>: a path to the new database to be created. This directory will be created when you execute the command—you cannot specify an existing directory.

• --language: the identifier for the language to create a database for. When used with --db-cluster, the option accepts a comma-separated list, or can be specified more than once. CodeQL supports creating databases for the following languages:

  Language	Identifier	Optional alternative identifiers (if any)
  C/C++	c-cpp	c or cpp
  C#	csharp
  GitHub Actions workflows	actions
  Go	go
  Java/Kotlin	java-kotlin	java or kotlin
  JavaScript/TypeScript	javascript-typescript	javascript or typescript
  Python	python
  Ruby	ruby
  Rust	rust
  Swift	swift

  Note

  If you specify one of the alternative identifiers, this is equivalent to using the standard language identifier. For example, specifying javascript instead of javascript-typescript will not exclude analysis of TypeScript code. Instead, you can use the --codescanning-config CLI option to load a configuration file that specifies files to exclude with the paths-ignore configuration key. See Workflow configuration options for code scanning.

  Alternatively, for languages that support it, use a custom build command that only builds the files that you want to scan. See Creating databases for compiled languages.

If your codebase has a build command or script that invokes the build process, we recommend that you specify it as well:

   codeql database create <database> --command <build> \
         --language=<language-identifier>

Options for creating databases

You can specify additional options depending on the location of your source file, if the code needs to be compiled, and if you want to create CodeQL databases for more than one language.

Option	Required	Usage
<database>		Specify the name and location of a directory to create for the CodeQL database. The command will fail if you try to overwrite an existing directory. If you also specify --db-cluster, this is the parent directory and a subdirectory is created for each language analyzed.
--language		Specify the identifier for the language to create a database for, one of: c-cpp, csharp, go, java-kotlin, javascript-typescript, python, ruby, rust and swift. When used with --db-cluster, the option accepts a comma-separated list, or can be specified more than once.
--command		Recommended. Use to specify the build command or script that invokes the build process for the codebase. Commands are run from the current folder or, where it is defined, from --source-root. Not needed for Python and JavaScript/TypeScript analysis.
--build-mode		Recommended. Use for C/C++, C#, Java and Rust when not providing a --command to specify whether to create a CodeQL database without a build (none) or by attempting to automatically detect a build command (autobuild). By default, autobuild detection is used. For a comparison of build modes, see CodeQL build modes.
--db-cluster		Use in multi-language codebases to generate one database for each language specified by --language.
--no-run-unnecessary-builds		Recommended. Use to suppress the build command for languages where the CodeQL CLI does not need to monitor the build (for example, Python and JavaScript/TypeScript).
--source-root		Use if you run the CLI outside the checkout root of the repository. By default, the database create command assumes that the current directory is the root directory for the source files, use this option to specify a different location.
--codescanning-config		Advanced. Use if you have a configuration file that specifies how to create the CodeQL databases and what queries to run in later steps. For more information, see Workflow configuration options for code scanning and database create.

You can specify extractor options to customize the behavior of extractors that create CodeQL databases. For more information, see Extractor options.

For full details of all the options you can use when creating databases, see database create.

Single language example

This example creates a single CodeQL database for the repository checked out at /checkouts/example-repo. It uses the JavaScript extractor to create a hierarchical representation of the JavaScript and TypeScript code in the repository. The resulting database is stored in /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript-typescript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Multiple language example

This example creates two CodeQL databases for the repository checked out at