codeql

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:

Language
Identifier
Alternatives

C/C++
c-cpp
c, cpp

C#
csharp
—

Go
go
—

Java/Kotlin
java-kotlin
java, kotlin

JavaScript/TypeScript
javascript-typescript
javascript, typescript

Python
python
—

Ruby
ruby
—

Rust
rust
—

Swift
swift
—

GitHub Actions
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 on the init action to cache restored dependencies across runs.

Analysis category: Use category to distinguish SARIF results in monorepos (e.g., per-language, per-component).

Step 6: Monorepo Configuration

For monorepos with multiple components, use the category parameter to separate SARIF results:

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 fails or custom build commands are needed:

- language: c-cpp
  build-mode: manual

Then add explicit build steps between init and 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 environment variable with security-events: write permission.

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

Problem
Solution

Workflow not triggering
Verify on: triggers match event; check paths/branches filters; ensure workflow exists on target branch

Resource not accessible error
Add security-events: write and contents: read permissions

Autobuild failure
Switch to build-mode: manual and add explicit build commands

No source code seen
Verify --source-root, build command, and language identifier

C# compiler failure
Check for /p:EmitCompilerGeneratedFiles=true conflicts with .sqlproj or legacy projects

Fewer lines scanned than expected
Switch from none to autobuild/manual; verify build compiles all source

Kotlin in no-build mode
Disable and re-enable default setup to switch to autobuild

Cache miss every run
Verify dependency-caching: true on init action

Out of disk/memory
Use larger runners; reduce analysis scope via paths config; use build-mode: none

SARIF upload fails
Ensure token has security-events: write; check 10 MB file size limit

SARIF results exceed limits
Split across multiple uploads with different --sarif-category; reduce query scope

Two CodeQL workflows
Disable default setup if using advanced setup, or remove old workflow file

Slow analysis
Enable dependency caching; use --threads=0; reduce query suite scope

For comprehensive troubleshooting with detailed solutions, search references/troubleshooting.md.

Hardware Requirements (Self-Hosted Runners)

Codebase Size
RAM
CPU

Small (<100K LOC)
8 GB+
2 cores

Medium (100K–1M LOC)
16 GB+
4–8 cores

Large (>1M LOC)
64 GB+
8 cores

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