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. 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.

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. We recommend scanning both on push and on a schedule.

Scanning code on every push to the repository 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.

Note: Code scanning doesn't currently support using the pull_request event to trigger a scan.

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 for branches that you specify. Because code scanning will not analyze code on other branches, developers could introduce new vulnerabilities or errors on other branches and then merge the code into the default branch.

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 on push. 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

Adding build steps for a compiled language

For 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.

If the C/C++, C#, or Java in your repository has a non-standard build process, autobuild may fail. If this happens, remove the autobuild action from the workflow, and uncomment the run step.

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."

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. An example configuration file is shown below.

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

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 file

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, including all of its subdirectories except for one called node_modules.

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/'
paths:
  - '/src' 

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