Configuring code scanning

You can configure how GitHub scans the code in your project for vulnerabilities and errors.

People with write permissions to a repository can configure code scanning for the repository.

In this article

Note: Code scanning is currently in beta and subject to change. To request access to the beta, join the waitlist.

About code scanning configuration

Code scanning uses GitHub Actions. Before you can configure code scanning for a repository, you must enable code scanning by adding a GitHub Actions workflow to the repository. For more information, see "Enabling code scanning."

Typically, you don't need to edit the default workflow for code scanning. However, if required, you can edit the workflow to specify the frequency of scans, the languages or directories to scan, and what code scanning looks for in your code. You might also need to edit the workflow if you use a specific set of commands to compile your code or if there is more than one compiled language in your repository.

Editing a code scanning workflow

GitHub saves workflow files in the .github/workflows directory of your repository. You can find the workflow by searching for its file name. For example, the default workflow file for CodeQL code scanning is called codeql-analysis.yml.

  1. In your repository, browse to the workflow file you want to edit.
  2. In the upper right corner of the file view, to open the workflow editor, click .
    Edit workflow file button
  3. After you have edited the file, click Start commit and complete the "Commit changes" form. You can choose to commit directly to the current branch, or create a new branch and start a pull request.
    Commit update to codeql.yml workflow

For more information about editing workflow files, see "Configuring a workflow."

Configuring frequency

You can scan code on a schedule or when specific events occur in a repository.

For example, the following configuration scans on push, on creation of a pull request, and on a schedule.

on:
  push:
  pull_request:
  schedule:
    - cron: '0 15 * * 0'

Scanning code on every push to the repository, and every time a pull request is created, prevents developers from introducing new vulnerabilities and errors into the code. Scanning code on a schedule informs you about the latest vulnerabilities and errors that GitHub, security researchers, and the community discover, even when developers aren't actively maintaining the repository.

Scanning on push

The default code scanning workflow uses the on.push event to trigger a code scan on every push to any branch containing the workflow file. For more information, see "Workflow syntax for GitHub Actions."

We don't recommend using the branches keyword to limit on.push to specific branches. If you specify branches for on.push, code scanning will only run when you push branches that you specify in the workflow.

Scanning pull requests

The default code scanning workflow uses the pull_request event to trigger a code scan on the HEAD commit of a pull request. Scanning on the pull_request event doesn't work if you open a pull request from a private fork.

For more information about the pull_request event, see "Workflow syntax for GitHub Actions."

Scanning on a schedule

If you use the default workflow, code scanning will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the cron value in the workflow. For more information, see "Workflow syntax for GitHub Actions."

Note: GitHub only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch.

Specifying an operating system

If your code requires a specific operating system to compile, you can configure this in your workflow. Edit the value of jobs.<job_id>.runs-on to specify the operating system for the machine that runs your code scanning actions. Code scanning supports the latest versions of macOS, Ubuntu, and Windows. For more information, see "Workflow syntax for GitHub Actions."

Overriding automatic language detection

Code scanning automatically detects and scans code written in the supported languages.

  • C/C++
  • C#
  • Go
  • Java
  • JavaScript/TypeScript
  • Python

If your repository contains code in multiple languages, you can specify the languages you want to analyze. There are several reasons you might want to prevent a language being analyzed. For example, the project might have dependencies in a different language to the main body of your code, and you might prefer not to see alerts for those dependencies.

To override automatic language detection, add with:languages: to the init action in your workflow. The keywords for the supported languages are cpp, csharp, go, java, javascript, and python.

For example, the following configuration limits code scanning to C/C++, C#, and Python.

- uses: github/codeql-action/init@v1
  with:
    languages: cpp, csharp, python

Configuring code scanning for compiled languages

For compiled languages like C/C++, C#, and Java, the autobuild step in the default workflow attempts to build code before the action performs CodeQL analysis. In contrast to the other compiled languages, CodeQL analyzes Go without building the code.

The autobuild process only ever attempts to build one compiled language for a repository. The language automatically selected for analysis is the language with most files.

If the C/C++, C#, or Java code in your repository has a non-standard build process or if it's written in more than one compiled language, autobuild may fail. You will need to remove the autobuild step from the workflow, and manually add build steps. For more information about how to configure code scanning for compiled languages, see "Configuring code scanning for compiled languages."

Accessing private repositories

If your workflow for code scanning accesses private repositories on GitHub, you'll need to configure Git to authenticate with a personal access token. Define the secret in the runner environment by using jobs.<job_id>.steps.env in your workflow before any CodeQL actions. For more information, see "Creating a personal access token for the command line" and "Creating and storing encrypted secrets."

For example, the following configuration has Git replace the full URLs to the github/foo, github/bar, and github/baz repositories on GitHub.com with URLs that include the personal access token that you store in the ACCESS_TOKEN environment variable.

steps:
- name: Configure access to private repository on GitHub.com
  env:
    TOKEN: ${{ secrets.ACCESS_TOKEN }}
  run: |
    git config --global url."https://${TOKEN}@github.com/github/foo".insteadOf "https://github.com/github/foo"
    git config --global url."https://${TOKEN}@github.com/github/bar".insteadOf "https://github.com/github/bar"
    git config --global url."https://${TOKEN}@github.com/github/baz".insteadOf "https://github.com/github/baz"

Using a custom configuration

You can write a configuration file for code scanning. A configuration file can specify which queries to run and which directories to scan.

Use the config-file parameter of the init action to specify the configuration file. The value of config-file is the path to the configuration file you want to use. This example loads the configuration file ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml

The configuration file must be located within the local repository. For examples of configuration files, see "Example configuration files."

Running additional queries

When you enable code scanning, GitHub's CodeQL analysis engine generates a database from the code and runs queries on it. For more information, see "About code scanning."

You can run additional queries by specifying these in a configuration file. The queries you want to run must belong to a QL pack and can be in your own repository or any public repository. For more information, see "About QL packs."

Queries must only depend on the standard libraries (that is, the libraries referenced by an import LANGUAGE statement in your query), or libraries in the same QL pack as the query. The standard libraries are located in the github/codeql repository. For more information, see "Introduction to query files."

You can specify a single .ql file, a directory containing multiple .ql files, a .qls query suite definition file, or any combination. For more information about query suite definitions, see "Creating CodeQL query suites."

To add one or more queries, add a queries section to your configuration file.

queries:
  - name: DESCRIPTION OF YOUR CHOICE
    uses: PATH

You can also run additional query suites by specifying these in a configuration file. Query suites are collections of queries, usually grouped by purpose or language.

The following query suites are built into code scanning and available for use in your configuration file.

Query suiteDescription
security-extendedQueries of lower severity and precision than the default queries
security-and-qualityQueries from security-extended, plus maintainability and reliability queries

When you specify a query suite in your configuration file, the CodeQL analysis engine will run the queries contained in the suite for you, in addition to the default set of queries.

To add one or more query suites, add a queries section to your configuration file.

queries:
 - uses: security-and-quality

We don't recommend referencing query suites for uses directly from the github/codeql repository, like github/codeql/cpp/ql/src@master. Such queries may not be compiled with the same version of CodeQL as the version used in your configuration file, which could lead to errors during analysis.

Disabling the default queries

If you only want to run custom queries, you can disable the default security queries by adding disable-default-queries: true to your configuration file.

Specifying directories to scan

For the interpreted languages that CodeQL supports (Python and JavaScript/TypeScript), you can restrict code scanning to files in specific directories by using the paths keyword in the configuration file. You can exclude the files in specific directories from scans by using the paths-ignore keyword.

Note: The paths and paths-ignore keywords, used in the context of the code scanning configuration file, should not be confused with the same keywords when used for on.<push|pull_request>.paths. When they are used to modify on.<push|pull_request> in a workflow file, they determine whether the actions will be run when someone modifies code in the specified directories. For more information, see "Workflow syntax for GitHub Actions."

For C/C++, C#, and Java, if you want to limit code scanning to specific directories in your project, you must specify appropriate build steps in the workflow. The commands you need to use to exclude a directory from the build will depend on your build system. For more information, see "Adding build steps for a compiled language."

You can quickly analyze small portions of a monorepo when you modify code in specific directories. You'll need to both exclude directories in your build steps and use the paths-ignore and paths keywords for on.<push|pull_request> in your workflow file.

Example configuration files

This configuration file adds the security-and-quality query suite to the list of queries run by CodeQL when scanning your code. For more information about the query suites available for use, see "Running additional queries."

name: "My CodeQL config"

queries:
  - uses: security-and-quality

This configuration file disables the default queries and specifies a set of custom queries to run instead. It also configures CodeQL to scan files in the src directory (relative to the root), and to exclude the node_modules directory (still relative to the root), as well as any file whose name ends in .test.js.

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@master
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@master
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths-ignore: 
  - node_modules
  - '**/*.test.js'
paths:
  - src 

Note: ** characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix ** and other characters. For example, foo/**, **/foo, and foo/**/bar are all allowed syntax, but **foo isn't. However you can use single stars along with other characters, as shown in the example. You'll need to quote anything that contains a single * character.

Using a third-party code scanning tool

You can display code analysis from a third-party tool in GitHub by adding the upload-sarif action to your workflow. For more information, see "Uploading a SARIF file to GitHub."

Ask a human

Can't find what you're looking for?

Contact us