CodeQL Code Scanning

This skill provides procedural guidance for configuring and running CodeQL code scanning — both through GitHub Actions workflows and the standalone CodeQL CLI.

When to Use This Skill

Use this skill when the request involves:

• Creating or customizing a

  codeql.yml

  GitHub Actions workflow
• Choosing between default setup and advanced setup for code scanning
• Configuring CodeQL language matrix, build modes, or query suites
• Running CodeQL CLI locally (

  codeql database create

  ,

  database analyze

  ,

  github upload-results

  )
• Understanding or interpreting SARIF output from CodeQL
• Troubleshooting CodeQL analysis failures (build modes, compiled languages, runner requirements)
• Setting up CodeQL for monorepos with per-component scanning
• Configuring dependency caching, custom query packs, or model packs

Supported Languages

CodeQL supports the following language identifiers:

c-cpp

c

cpp

csharp

go

java-kotlin

java

kotlin

javascript-typescript

javascript

typescript

python

ruby

rust

swift

actions

Alternative identifiers are equivalent to the standard identifier (e.g.,

javascript

does not exclude TypeScript analysis).

Core Workflow — GitHub Actions

Step 1: Choose Setup Type

• Default setup — Enable from repository Settings → Advanced Security → CodeQL analysis. Best for getting started quickly. Uses

  none

  build mode for most languages.
• Advanced setup — Create a

  .github/workflows/codeql.yml

  file for full control over triggers, build modes, query suites, and matrix strategies.

To switch from default to advanced: disable default setup first, then commit the workflow file.

Step 2: Configure Workflow Triggers

Define when scanning runs:

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'  # Weekly Monday 6:30 UTC

• push

  — scans on every push to specified branches; results appear in Security tab

• pull_request

  — scans PR merge commits; results appear as PR check annotations

• schedule

  — periodic scans of the default branch (cron must exist on default branch)

• merge_group

  — add if repository uses merge queues

To skip scans for documentation-only PRs:

on:
  pull_request:
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

paths-ignore

controls whether the workflow runs, not which files are analyzed.

Step 3: Configure Permissions

Set least-privilege permissions:

permissions:
  security-events: write   # Required to upload SARIF results
  contents: read            # Required to checkout code
  actions: read             # Required for private repos using codeql-action

Step 4: Configure Language Matrix

Use a matrix strategy to analyze each language in parallel:

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

For compiled languages, set the appropriate

build-mode

• none

  — no build required (supported for C/C++, C#, Java, Rust)

• autobuild

  — automatic build detection

• manual

  — custom build commands (advanced setup only)

For detailed per-language autobuild behavior and runner requirements, search

references/compiled-languages.md

.

Step 5: Configure CodeQL Init and Analysis

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

  - name: Initialize CodeQL
    uses: github/codeql-action/init@v4
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}
      queries: security-extended
      dependency-caching: true

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

Query suite options:

• security-extended

  — default security queries plus additional coverage

• security-and-quality

  — security plus code quality queries
• Custom query packs via

  packs:

  input (e.g.,

  codeql/javascript-queries:AlertSuppression.ql

  )

Dependency caching: Set

dependency-caching: true

init

Analysis category: Use

category

Step 6: Monorepo Configuration

For monorepos with multiple components, use the

category

category: "/language:${{ matrix.language }}/component:frontend"

To restrict analysis to specific directories, use a CodeQL configuration file (

.github/codeql/codeql-config.yml

paths:
  - apps/
  - services/
paths-ignore:
  - node_modules/
  - '**/test/**'

Reference it in the workflow:

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

Step 7: Manual Build Steps (Compiled Languages)

If

autobuild

- language: c-cpp
  build-mode: manual

Then add explicit build steps between

init

analyze

- if: matrix.build-mode == 'manual'
  name: Build
  run: |
    make bootstrap
    make release

Core Workflow — CodeQL CLI

Step 1: Install the CodeQL CLI

Download the CodeQL bundle (includes CLI + precompiled queries):

# Download from https://github.com/github/codeql-action/releases
# Extract and add to PATH
export PATH="$HOME/codeql:$PATH"

# Verify installation
codeql resolve packs
codeql resolve languages

Always use the CodeQL bundle, not a standalone CLI download. The bundle ensures query compatibility and provides precompiled queries for better performance.

Step 2: Create a CodeQL Database

# Single language
codeql database create codeql-db \
  --language=javascript-typescript \
  --source-root=src

# Multiple languages (cluster mode)
codeql database create codeql-dbs \
  --db-cluster \
  --language=java,python \
  --command=./build.sh \
  --source-root=src

For compiled languages, provide the build command via

--command

Step 3: Analyze the Database

codeql database analyze codeql-db \
  javascript-code-scanning.qls \
  --format=sarif-latest \
  --sarif-category=javascript \
  --output=results.sarif

Common query suites:

<language>-code-scanning.qls

<language>-security-extended.qls

<language>-security-and-quality.qls

Step 4: Upload Results to GitHub

codeql github upload-results \
  --repository=owner/repo \
  --ref=refs/heads/main \
  --commit=<commit-sha> \
  --sarif=results.sarif

Requires

GITHUB_TOKEN

security-events: write

CLI Server Mode

To avoid repeated JVM initialization when running multiple commands:

codeql execute cli-server

For detailed CLI command reference, search

references/cli-commands.md

.

Alert Management

Severity Levels

Alerts have two severity dimensions:

• Standard severity:

  Error

  ,

  Warning

  ,

  Note

• Security severity:

  Critical

  ,

  High

  ,

  Medium

  ,

  Low

  (derived from CVSS scores; takes display precedence)

Copilot Autofix

GitHub Copilot Autofix generates fix suggestions for CodeQL alerts in pull requests automatically — no Copilot subscription required. Review suggestions carefully before committing.

Alert Triage in PRs

• Alerts appear as check annotations on changed lines
• Check fails by default for

  error

  /

  critical

  /

  high

  severity alerts
• Configure merge protection rulesets to customize the threshold
• Dismiss false positives with a documented reason for audit trail

For detailed alert management guidance, search

references/alert-management.md

.

Custom Queries and Packs

Using Custom Query Packs

- uses: github/codeql-action/init@v4
  with:
    packs: |
      my-org/my-security-queries@1.0.0
      codeql/javascript-queries:AlertSuppression.ql

Creating Custom Query Packs

Use the CodeQL CLI to create and publish packs:

# Initialize a new pack
codeql pack init my-org/my-queries

# Install dependencies
codeql pack install

# Publish to GitHub Container Registry
codeql pack publish

CodeQL Configuration File

For advanced query and path configuration, create

.github/codeql/codeql-config.yml

paths:
  - apps/
  - services/
paths-ignore:
  - '**/test/**'
  - node_modules/
queries:
  - uses: security-extended
packs:
  javascript-typescript:
    - my-org/my-custom-queries

Code Scanning Logs

Summary Metrics

Workflow logs include key metrics:

• Lines of code in codebase — baseline before extraction
• Lines extracted — including external libraries and auto-generated files
• Extraction errors/warnings — files that failed or produced warnings during extraction

Debug Logging

To enable detailed diagnostics:

• GitHub Actions: re-run the workflow with "Enable debug logging" checked
• CodeQL CLI: use

  --verbosity=progress++

  and

  --logdir=codeql-logs

Troubleshooting

Common Issues

on:

paths

branches

Resource not accessible

security-events: write

contents: read

build-mode: manual

--source-root

/p:EmitCompilerGeneratedFiles=true

.sqlproj

none

autobuild

manual

autobuild

dependency-caching: true

init

paths

build-mode: none

security-events: write

--sarif-category

--threads=0

For comprehensive troubleshooting with detailed solutions, search

references/troubleshooting.md

.

Hardware Requirements (Self-Hosted Runners)

All sizes: SSD with ≥14 GB free disk space.

Action Versioning

Pin CodeQL actions to a specific major version:

uses: github/codeql-action/init@v4      # Recommended
uses: github/codeql-action/autobuild@v4
uses: github/codeql-action/analyze@v4

For maximum security, pin to a full commit SHA instead of a version tag.

Reference Files

For detailed documentation, load the following reference files as needed:

• references/workflow-configuration.md

  — Full workflow trigger, runner, and configuration options
  • Search patterns:

    trigger

    ,

    schedule

    ,

    paths-ignore

    ,

    db-location

    ,

    model packs

    ,

    alert severity

    ,

    merge protection

    ,

    concurrency

    ,

    config file

• references/cli-commands.md

  — Complete CodeQL CLI command reference
  • Search patterns:

    database create

    ,

    database analyze

    ,

    upload-results

    ,

    resolve packs

    ,

    cli-server

    ,

    installation

    ,

    CI integration

• references/sarif-output.md

  — SARIF v2.1.0 object model, upload limits, and third-party support
  • Search patterns:

    sarifLog

    ,

    result

    ,

    location

    ,

    region

    ,

    codeFlow

    ,

    fingerprint

    ,

    suppression

    ,

    upload limits

    ,

    third-party

    ,

    precision

    ,

    security-severity

• references/compiled-languages.md

  — Build modes and autobuild behavior per language
  • Search patterns:

    C/C++

    ,

    C#

    ,

    Java

    ,

    Go

    ,

    Rust

    ,

    Swift

    ,

    autobuild

    ,

    build-mode

    ,

    hardware

    ,

    dependency caching

• references/troubleshooting.md

  — Comprehensive error diagnosis and resolution
  • Search patterns:

    no source code

    ,

    out of disk

    ,

    out of memory

    ,

    403

    ,

    C# compiler

    ,

    analysis too long

    ,

    fewer lines

    ,

    Kotlin

    ,

    extraction errors

    ,

    debug logging

    ,

    SARIF upload

    ,

    SARIF limits

• references/alert-management.md

  — Alert severity, triage, Copilot Autofix, and dismissal
  • Search patterns:

    severity

    ,

    security severity

    ,

    CVSS

    ,

    Copilot Autofix

    ,

    dismiss

    ,

    triage

    ,

    PR alerts

    ,

    data flow

    ,

    merge protection

    ,

    REST API