Skip to main content
Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Configuring CodeQL

Code Scanning Configuration Options

Code Scanning should be configured in a way that works for your repository, team, and Continuous Integration (CI) system. Use the sections below as a guide to which code scanning configuration option is best for you:

Default Code Scanning with CodeQL

The easiest option to get started with is Default Code Scanning with CodeQL. However, the “default” option may not be appropriate for all development teams and/or code repositories.

Your repository might be a good candidate for default code scanning if ALL of the following statements describe your codebase:

  • Includes at least one CodeQL-supported language.
  • Uses an interpreted (i.e. non-compiling) language that is supported by CodeQL, such as JavaScript/TypeScript, Python, or Ruby.

The official CodeQL documentation contains more information on which languages are supported:

To configure Default Code Scanning with CodeQL, an admin of the repository may navigate to the following tab in your repository:

Settings -> Code security and analysis

Under the “Code scanning” section, choose the default code scanning option by selecting:

Set up -> Default

Your configuration should look like the following:

Setting up Default Code Scanning

NOTE: Default code scanning is implemented as a single, standard workflow in GitHub Actions. After initial setup, this workflow can be customized and/or extended as needed.

Advanced Code Scanning with CodeQL and GitHub Actions

A highly flexible and best supported option for code scanning is to create a custom GitHub Actions workflow using actions from the github/codeql-actions repository. The workflow can and should be extended to meet the needs of your development team and/or code repository. For example, this option allows for language-specific dependencies (e.g. Java, Go, etc.) to be installed and for custom build commands to be run.

Your repository might be a good candidate for advanced code scanning with CodeQL if ANY of the following statements describe your codebase:

  • Includes at least one CodeQL-supported language.
  • Uses a compiled language that is supported by CodeQL, such as C, C++, C#, Go, Java, Kotlin, or Swift.
  • Requires a custom build command and/or build environment.

NOTE: This option may not be apporpriate for development teams that use a third-party system for Continuous Integration (CI). See the next section for more information.

The official CodeQL documentation contains more information on which languages CodeQL supports and how to customize the languages that are analyzed

Anyone with write access to the repository may implement advanced code scanning with CodeQL by committing a new GitHub Actions workflow under the .github/workflows directory of the repository. Similar to the process described above for setting up default code scanning, a starter workflow may be generated by using the GitHub UI.

Get started by following the official CodeQL documentation which provides details on how to customize your advanced setup for code scanning.

NOTE: GitHub Actions can be run on GitHub-hosted or self-hosted runners. Any build that requires access to internal resources on the VA network must use a self-hosted runner. For more information, see Self-hosted runners.

Advanced Code Scanning with CodeQL in Third-Party CI

Code scanning is required. Redefining your CI pipeline is not.

CodeQL may be leveraged for code scanning within your existing CI pipeline. While the details of this implementation will vary depending on your CI system, the general process is as follows:

  1. Use the official CodeQL documentation as a guide to install the CodeQL CLI on your CI system.
  2. Run the codeql database create command to create a CodeQL database from your source code.
  3. Run the codeql database analyze command to analyze the CodeQL database and generate SARIF results.
  4. Run the codeql github upload-results command to upload the SARIF results to GitHub’s Code Scanning Upload API.

Additional Help

For additional help, please contact the VA GitHub Support team by opening a new Consultation: CodeQL Configuration issue in the GitHub Users Request repo