Setting up CodeQL in Visual Studio Code

Overview

This topic explains how to install and configure the CodeQL extension for Visual Studio Code. There are three steps:

  1. Install the extension.
  2. Optional: configure access to a specific version of the CodeQL command-line interface.
  3. Set up your workspace.

Installing the extension

License notice

If you don’t have an Enterprise license then, by installing this product, you are agreeing to the GitHub CodeQL Terms and Conditions.

GitHub CodeQL can only be used on codebases that are released under an OSI-approved open source license, or to perform academic research. It can’t be used for automated analysis, continuous integration or continuous delivery, whether as part of normal software engineering processes or otherwise. For these uses, contact the sales team.

Note that the CodeQL extension requires a minimum of Visual Studio Code 1.39. Older versions are not supported.

You can install it using any of the normal methods for installing a VS Code extension:

  • Go to the Visual Studio Code Marketplace in your browser and click Install.
  • In the Extensions view (Ctrl+Shift+X or Cmd+Shift+X), search for CodeQL, then select Install.
  • Download the CodeQL VSIX file. Then, in the Extensions view, click More actions > Install from VSIX, and select the CodeQL VSIX file.

Configuring access to the CodeQL CLI

The extension uses the CodeQL CLI to compile and run queries.

If you already have the CLI installed and added to your PATH, the extension uses that version. This might be the case if you create your own CodeQL databases instead of downloading them from LGTM.com.

Otherwise, the extension automatically manages access to the executable of the CLI for you. This ensures that the CLI is compatible with the CodeQL extension. You can also check for updates with the CodeQL: Check for CLI Updates command.

Note

The extension-managed CLI is not accessible from the terminal. If you intend to use the CLI outside of the extension (for example to create databases), we recommend that you install your own copy of the CLI. To avoid having two copies of the CLI on your machine, you can specify your version of the CLI in the codeQL.cli.executablePath setting (see below).

If you want the extension to use a specific version of the CodeQL CLI executable, set codeQL.cli.executablePath in your VS Code user settings to the location of the executable file for the CLI. That is, the file named codeql (Linux/Mac) or codeql.cmd (Windows).

If you have any difficulty setting up access to the CodeQL CLI, see the CodeQL Extension Log in the Output panel for error messages.

Setting up a CodeQL workspace

When you’re working with CodeQL, you need access to the standard CodeQL libraries. This also makes a wide variety of queries available to explore.

There are two ways to do this:

  • Recommended, use the “starter” workspace. This is maintained as a Git repository which makes it easy to keep up-to-date with changes to the libraries.
  • More advanced, add the CodeQL libraries and queries to an existing workspace.

Note

For CLI users there is a third option: If you have followed the instructions in Getting started with the CodeQL CLI to create a CodeQL directory (for example codeql-home) containing the CodeQL libraries, you can open this directory in VS Code. This also gives the extension access to the CodeQL libraries.

Click to show information for LGTM Enterprise users

Your local version of the CodeQL queries and libraries should match your version of LGTM Enterprise. For example, if you use LGTM Enterprise 1.23, then you should clone the 1.23.0 branch of the starter workspace (or the appropriate 1.23.x branch, corresponding to each maintenance release).

This ensures that the queries and libraries you write in VS Code also work in the query console on LGTM Enterprise.

If you prefer to add the CodeQL queries and libraries to an existing workspace instead of the starter workspace, then you should clone the appropriate branch of the general CodeQL repository and the CodeQL repository for Go and add them to your workspace.

Using the “starter” workspace

The starter workspace is a Git repository. It contains:

  • The repository of CodeQL libraries and queries for C/C++, C#, Java, JavaScript, and Python. This is included as a submodule, so it can be updated without affecting your custom queries.
  • The repository of CodeQL libraries and queries for Go. This is also included as a submodule.
  • A series of folders named codeql-custom-queries-<language>. These are ready for you to start developing your own custom queries for each language, using the standard libraries. There are some example queries to get you started.

To use the starter workspace:

  1. Clone the https://github.com/github/vscode-codeql-starter/ repository to your computer:
    • Make sure you include the submodules, either by using git clone --recursive, or using by git submodule update --init --remote after cloning.
    • Use git submodule update --remote regularly to keep the submodules up to date.
  2. In VS Code, use the File > Open Workspace option to open the vscode-codeql-starter.code-workspace file from your checkout of the workspace repository.

Updating an existing workspace for CodeQL

You can add the CodeQL libraries to an existing workspace by making a local clone of the CodeQL repository directly: https://github.com/semmle/ql.

To make the standard libraries available in your workspace:

  1. Select File > Add Folder to Workspace, and choose your local checkout of the Semmle/ql repository.
  2. Create one new folder per target language, using either the New Folder or Add Folder to Workspace options, to hold custom queries and libraries.
  3. Create a qlpack.yml file in each target language folder. This tells the CodeQL CLI the target language for that folder and what its dependencies are. (The master branch of Semmle/ql already has these files.) CodeQL will look for the dependencies in all the open workspace folders, or on the user’s search path.

For example, to make a custom CodeQL folder called my-custom-cpp-pack depend on the CodeQL standard library for C++, create a qlpack.yml file with the following contents:

name: my-custom-cpp-pack
version: 0.0.0
libraryPathDependencies: codeql-cpp

For more information about why you need to add a qlpack.yml file, see the reference topic about QL packs.

Note

The CodeQL libraries for Go are not included in the Semmle/ql repository, but are stored separately. To analyze Go projects, clone the repository at https://github.com/github/codeql-go and add it to your workspace as above.

What next?