Continuous Integration #

CI/CD integration #

In this chapter, we will walk you through the process of enabling code scanning with CodeQL for your GitHub repository.

Code scanning is available for public GitHub repositories. Code scanning is also available for private repositories owned by organizations with a GitHub Advanced Security license. For more details we refer to the official documentation on GitHub Advanced Security.

Code scanning with CodeQL #

GitHub code scanning is a static-analysis framework powered by CodeQL. By enabling code scanning for your repository, you will automatically be notified about any issues detected by the framework. To enable code scanning for a GitHub repository, navigate to “Code security and analysis” on the GitHub repository settings page and enable “GitHub Advanced Security.” This allows you to set up code scanning with CodeQL.

The code scanning dialog allows you to set up code scanning with either a default or custom configuration. The default configuration is a good starting point and will enable a set of query suites based on the language used in the repository.

The default configuration is a simple way to get started with code scanning, but may not always work for more complex projects. In particular, if the project contains code in a compiled language like C or C++, the automatic setup may fail to detect the build system used by the project.

If automatic setup fails, or if you would like to use custom queries as part of code scanning, we recommend using the advanced setup option. This will add to the repository a new code scanning workflow configuration that can be edited to add additional languages, custom build scripts, and new query packs.

name: "CodeQL"

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  schedule:
    - cron: '34 10 * * 6'

jobs:
  analyze:
    name: Analyze

    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
    timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }}

    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: [ 'cpp' ]
        # If your project contains more than one language supported by CodeQL you simply
        # list all of the language identifiers here. The workflow will run once for each
        # included language.

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    # Initializes the CodeQL tools for scanning.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@v2
      with:
        languages: ${{ matrix.language }}
        # If you wish to specify custom queries, you can do so here or in a config file.
        # By default, queries listed here will override any specified in a config file.
        # Prefix the list here with "+" to use these queries and those in the config file.

        # queries: security-extended,security-and-quality

    # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift).
    # If this step fails, then you should remove it and run the build manually (see below)
    - name: Autobuild
      uses: github/codeql-action/autobuild@v2

    #   If the Autobuild fails above, remove it and uncomment the following three lines,
    #   suitably modified to build the codebase.

    # - run: |
    #     echo "Run, Build Application using script"
    #     ./location_of_script_within_repo/buildscript.sh

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      with:
        category: "/language:${{matrix.language}}"

For compiled languages, you may need to update the workflow configuration by replacing the autobuild job with a custom build command or script, as indicated above.

Code scanning with custom queries #

To configure the query suites and query packs used by code scanning, you need to choose the advanced option and manually specify the query packs to run. This is done by editing the “Initialize CodeQL” section of the workflow configuration. It is possible to specify query suites and individual queries using queries, as well as published query packs using packs.

- uses: github/codeql-action/init@v2
  with:
    queries: security-extended,security-and-quality
    packs: trailofbits/cpp-queries

This example adds security-extended and security-and-quality query suites from GitHub, as well as the trailofbits/cpp-queries query pack.

Code scanning with repository local queries #

It is also possible to include queries from the current repository as part of code scanning. For example, if the repository contains the CodeQL query codeql/UnhandledError.ql, this can be run as part of the code scanning workflow by adding the query to the workflow configuration under queries as follows:

- uses: github/codeql-action/init@v2
  with:
    queries: ./codeql/UnhandledError.ql
    packs: trailofbits/cpp-queries

The code scanning results will now include any issues identified by the local UnhandledError.ql query as well as any issues identified by the trailofbits/cpp-queries query pack.

Note the . at the start of the query path. This is needed to identify the query name as a repository relative path.

Remember that all queries must be part of a query pack. For queries checked in to the current repository, this means that there must be a corresponding qlpack.yml file checked in to the root directory of the corresponding query pack.

For more information on qlpack.yml files, see Creating new query packs.

If you have more than one or two repository local queries that you would like to run as part of CI/CD, it is probably better to install the query pack locally using codeql pack install and then specify the name of the query pack directly in the workflow configuration under packs.

Triaging code scanning results #

Code scanning results can be found under the “Security” tab in your repository.

It is also possible to set up branch protection rules based on code scanning results on the repository settings page under “Code Security and Analysis.”