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:

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

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

CodeQL Alert Management Reference

Guide for understanding, triaging, dismissing, and resolving code scanning alerts generated by CodeQL.

Alert Severity Levels

Standard Severity

All code scanning alerts have one of these severity levels:

Security Severity

Security alerts additionally have a security severity derived from CVSS scores:

When a security severity is present, it takes precedence over the standard severity for display and sorting.

How Security Severity Is Calculated

For each CodeQL security query added to the Default or Extended suite: 1. All CVEs matching the query's CWE tags are identified 2. The 75th percentile of CVSS scores for those CVEs is calculated 3. That score becomes the query's security severity 4. The numerical score maps to Critical/High/Medium/Low per CVSS definitions

Alert Labels

Alerts in non-application code receive category labels:

These labels are assigned automatically based on file paths. They cannot be manually overridden.

Alert Triage in Pull Requests

How PR Alerts Work

• Alerts appear as annotations in the Conversation tab and Files changed tab
• The Code scanning results check summarizes all findings
• Alerts only appear in a PR if ALL identified lines exist in the PR diff
• New alerts on changed lines are shown; pre-existing alerts are not

PR Check Failure Behavior

By default, the check fails if alerts have severity of error, critical, or high. Override this threshold via repository Settings → Rules → Rulesets → Code scanning.

Merge Protection

Configure rulesets to block PR merging when:

• A required tool finds alerts matching the severity threshold
• A required tool's analysis is still in progress
• A required tool is not configured for the repository

Copilot Autofix

GitHub Copilot Autofix automatically generates fix suggestions for CodeQL alerts in pull requests.

Availability

• Free for all public repositories
• Available for private repos with GitHub Code Security license
• No Copilot subscription required
• Supports a subset of CodeQL queries (not all)

How It Works

1. Code scanning detects an alert in a PR 2. Alert information is sent to the LLM for analysis 3. Fix suggestions are posted as PR comments with inline code changes 4. Developers review, edit, and commit the suggested fix

Using Autofix Suggestions

• Click Edit to apply the fix directly on GitHub or via GitHub CLI
• Use View autofix patch to apply locally
• Always review and test the fix before committing
• The fix may include changes to files not in the original PR diff (e.g., adding a dependency to package.json)

Dismissing Autofix

Click Dismiss suggestion on the comment to reject a suggestion.

Dismissing Alerts

When to Dismiss

Dismiss alerts when:

• The finding is a false positive (code uses a pattern CodeQL doesn't recognize as safe)
• The code is used only for testing and risk is acceptable
• The effort to fix is greater than the benefit

Dismissal Reasons

Choose the appropriate reason — it affects whether the query continues running:

Dismissal Comments

• Add a comment explaining the dismissal rationale
• Comments are stored in the alert timeline for audit/compliance
• Accessible via REST API at alerts/{alert_number} → dismissed_comment

Contributing Improvements

For false positives from unsupported sanitization libraries, consider contributing to the CodeQL repository to improve analysis accuracy.

Resolving Alerts

Fix and Re-scan

1. Fix the vulnerability in the source code 2. Commit and push the changes 3. The next code scanning run will verify the fix 4. Alert is automatically closed when the fix is confirmed

Removing Stale Configurations

If alerts persist from old/disabled configurations: 1. Navigate to the alert's Affected branches section 2. Identify stale configurations 3. Delete the stale configuration to remove outdated alerts

Alert Data Flow

For path-problem queries, alerts include data flow information:

• Source — where untrusted data enters (e.g., user input)
• Sink — where the data is used unsafely (e.g., SQL query, HTML output)
• Path — the intermediate steps data takes from source to sink

Click Show paths on alert annotations to visualize the full data flow.

Multi-Configuration Alerts

When multiple code scanning configurations analyze the same file:

• The same problem detected by the same query appears as a single alert
• The Affected branches section shows which configurations found the alert
• Different configurations may show different statuses
• Re-run out-of-date configurations to synchronize alert statuses

Viewing Alerts

Repository Security Tab

• Navigate to Security → Code scanning alerts
• Filter by: tool, severity, rule, branch, state
• Click an alert to see full details, affected branches, and data flow

Pull Request Checks

• View Code scanning results check in the PR
• Click View all branch alerts for the full alert list
• Annotations appear inline in Files changed

REST API

• GET /repos/{owner}/{repo}/code-scanning/alerts — list alerts
• GET /repos/{owner}/{repo}/code-scanning/alerts/{alert_number} — get alert details
• PATCH /repos/{owner}/{repo}/code-scanning/alerts/{alert_number} — update alert status

CodeQL CLI Command Reference

Detailed reference for the CodeQL CLI — installation, database creation, analysis, SARIF upload, and CI integration.

Installation

Download the CodeQL Bundle

Always download the CodeQL bundle (CLI + precompiled queries) from: https://github.com/github/codeql-action/releases

The bundle includes:

• CodeQL CLI product
• Compatible queries and libraries from github/codeql
• Precompiled query plans for faster analysis

Platform-Specific Bundles

.tar.gz variants are also available for systems without Zstandard support.

Setup

# Extract the bundle
tar xf codeql-bundle-linux64.tar.zst

# Add to PATH
export PATH="$HOME/codeql:$PATH"

# Verify installation
codeql resolve packs
codeql resolve languages

codeql resolve packs should list available query packs for all supported languages. If packs are missing, verify you downloaded the bundle (not standalone CLI).

CI System Setup

Ensure the full CodeQL bundle contents are available on every CI server:

• Copy from a central location and extract on each server, or
• Use the GitHub REST API to download the bundle dynamically per run

Core Commands

codeql database create

Create a CodeQL database from source code.

# Basic usage (interpreted language)
codeql database create <output-dir> \
  --language=<language> \
  --source-root=<source-dir>

# Compiled language with build command
codeql database create <output-dir> \
  --language=java-kotlin \
  --command='./gradlew build' \
  --source-root=.

# Multiple languages (cluster mode)
codeql database create <output-dir> \
  --db-cluster \
  --language=java,python,javascript-typescript \
  --command='./build.sh' \
  --source-root=.

Key flags:

codeql database analyze

Run queries against a CodeQL database and produce SARIF output.

codeql database analyze <database-dir> \
  <query-suite-or-pack> \
  --format=sarif-latest \
  --sarif-category=<category> \
  --output=<output-file>

Key flags:

Common query suites:

Examples:

# JavaScript analysis with extended security
codeql database analyze codeql-db/javascript-typescript \
  javascript-typescript-security-extended.qls \
  --format=sarif-latest \
  --sarif-category=javascript \
  --output=js-results.sarif

# Java analysis with all available threads
codeql database analyze codeql-db/java-kotlin \
  java-kotlin-code-scanning.qls \
  --format=sarif-latest \
  --sarif-category=java \
  --output=java-results.sarif \
  --threads=0

# Include file contents in SARIF
codeql database analyze codeql-db \
  javascript-typescript-code-scanning.qls \
  --format=sarif-latest \
  --output=results.sarif \
  --sarif-add-file-contents

codeql github upload-results

Upload SARIF results to GitHub code scanning.

codeql github upload-results \
  --repository=<owner/repo> \
  --ref=<git-ref> \
  --commit=<commit-sha> \
  --sarif=<sarif-file>

Key flags:

Authentication: Set GITHUB_TOKEN environment variable with a token that has security-events: write scope, or use --github-auth-stdin.

codeql resolve packs

List available query packs:

codeql resolve packs

Use to verify installation and diagnose missing packs. Available since CLI v2.19.0 (earlier versions: use codeql resolve qlpacks).

codeql resolve languages

List supported languages:

codeql resolve languages

Shows which language extractors are available in the current installation.

codeql database bundle

Create a relocatable archive of a CodeQL database for sharing or troubleshooting:

codeql database bundle <database-dir> \
  --output=<archive-file>

Useful for sharing databases with team members or GitHub Support.

CLI Server Mode

codeql execute cli-server

Run a persistent server to avoid repeated JVM initialization when executing multiple commands:

codeql execute cli-server [options]

Key flags:

The server accepts commands via stdin and returns results, keeping the JVM warm between commands. Primarily useful in CI environments running multiple sequential CodeQL commands.

CI Integration Pattern

Complete CI Script Example

#!/bin/bash
set -euo pipefail

REPO="my-org/my-repo"
REF="refs/heads/main"
COMMIT=$(git rev-parse HEAD)
LANGUAGES=("javascript-typescript" "python")

# Create databases for all languages
codeql database create codeql-dbs \
  --db-cluster \
  --source-root=. \
  --language=$(IFS=,; echo "${LANGUAGES[*]}")

# Analyze each language and upload results
for lang in "${LANGUAGES[@]}"; do
  echo "Analyzing $lang..."

  codeql database analyze "codeql-dbs/$lang" \
    "${lang}-security-extended.qls" \
    --format=sarif-latest \
    --sarif-category="$lang" \
    --output="${lang}-results.sarif" \
    --threads=0

  codeql github upload-results \
    --repository="$REPO" \
    --ref="$REF" \
    --commit="$COMMIT" \
    --sarif="${lang}-results.sarif"

  echo "$lang analysis uploaded."
done

External CI Systems

For CI systems other than GitHub Actions: 1. Install the CodeQL bundle on CI runners 2. Run codeql database create with appropriate build commands 3. Run codeql database analyze to generate SARIF 4. Run codeql github upload-results to push results to GitHub 5. Set GITHUB_TOKEN with security-events: write permission

Environment Variables

CodeQL Build Modes for Compiled Languages

Detailed reference for how CodeQL handles compiled language analysis, including build modes, autobuild behavior, runner requirements, and hardware specifications.

Build Modes Overview

CodeQL offers three build modes for compiled languages:

C/C++

Supported Build Modes

none, autobuild, manual

Default setup mode: none

No Build (none)

• Infers compilation units through source file extensions
• Compilation flags and include paths inferred by inspecting the codebase
• No working build command needed

Accuracy considerations:

• May be less accurate if code depends heavily on custom macros/defines not in existing headers
• May miss accuracy when codebase has many external dependencies

Improving accuracy:

• Place custom macros/defines in header files included by source files
• Ensure external dependencies (headers) are available in system include directories or workspace
• Run extraction on the target platform (e.g., Windows runner for Windows projects)

Autobuild

Windows autodetection: 1. Invoke MSBuild.exe on .sln or .vcxproj closest to root 2. If multiple files at same depth, attempts to build all 3. Falls back to build scripts: build.bat, build.cmd, build.exe

Linux/macOS autodetection: 1. Look for build system in root directory 2. If not found, search subdirectories for unique build system 3. Run appropriate configure/build command

Supported build systems: MSBuild, Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild, build scripts

Runner Requirements (C/C++)

• Ubuntu: gcc compiler; may need clang or msvc. Build tools: msbuild, make, cmake, bazel. Utilities: python, perl, lex, yacc.
• Auto-install dependencies: Set CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES=true (enabled by default on GitHub-hosted; disabled on self-hosted). Requires Ubuntu with passwordless sudo apt-get.
• Windows: powershell.exe in PATH

C\#

Supported Build Modes

none, autobuild, manual

Default setup mode: none

No Build (none)

• Restores dependencies using heuristics from: *.csproj, *.sln, nuget.config, packages.config, global.json, project.assets.json
• Uses private NuGet feeds if configured for the organization
• Generates additional source files for accuracy:
• Global using directives (implicit using feature)
• ASP.NET Core .cshtml → .cs conversion

Accuracy considerations:

• Requires internet access or private NuGet feed
• Multiple versions of same NuGet dependency may cause issues (CodeQL picks newer version)
• Multiple .NET framework versions may affect accuracy
• Colliding class names cause missing method call targets

Autobuild

Windows autodetection: 1. dotnet build on .sln or .csproj closest to root 2. MSBuild.exe on solution/project files 3. Build scripts: build.bat, build.cmd, build.exe

Linux/macOS autodetection: 1. dotnet build on .sln or .csproj closest to root 2. MSbuild on solution/project files 3. Build scripts: build, build.sh

Injected Compiler Flags (Manual Builds)

The CodeQL tracer injects these flags into C# compiler invocations:

/p:EmitCompilerGeneratedFiles=true may cause issues with legacy projects or .sqlproj files.

Runner Requirements (C#)

• .NET Core: .NET SDK (for dotnet)
• .NET Framework (Windows): Microsoft Build Tools + NuGet CLI
• .NET Framework (Linux/macOS): Mono Runtime (mono, msbuild, nuget)
• `build-mode: none`: Requires internet access or private NuGet feed

Go

Supported Build Modes

autobuild, manual (no none mode)

Default setup mode: autobuild

Autobuild

Autodetection sequence: 1. Invoke make, ninja, ./build, or ./build.sh until one succeeds and go list ./... works 2. If none succeed, look for go.mod (go get), Gopkg.toml (dep ensure -v), or glide.yaml (glide install) 3. If no dependency managers found, rearrange directory for GOPATH and use go get 4. Extract all Go code (similar to go build ./...)

Default setup automatically detects go.mod and installs compatible Go version.

Extractor Options

Java/Kotlin

Supported Build Modes

• Java: none, autobuild, manual
• Kotlin: autobuild, manual (no none mode)

Default setup mode:

• Java only: none
• Kotlin or Java+Kotlin: autobuild

If Kotlin code is added to a repo using none mode, disable and re-enable default setup to switch to autobuild.

No Build (none) — Java Only

• Runs Gradle or Maven for dependency information (not actual build)
• Queries each root build file; prefers newer dependency versions on clash
• Uses private Maven registries if configured

Accuracy considerations:

• Build scripts that can't be queried for dependencies may cause inaccurate guesses
• Code generated during normal build process will be missed
• Multiple versions of same dependency (CodeQL picks newer)
• Multiple JDK versions — CodeQL uses highest found; lower-version files may be partially analyzed
• Colliding class names cause missing method call targets

Autobuild

Autodetection sequence: 1. Search root directory for Gradle, Maven, Ant build files 2. Run first found (Gradle preferred over Maven) 3. Otherwise, search for build scripts

Build systems: Gradle, Maven, Ant

Runner Requirements (Java)

• JDK (appropriate version for the project)
• Gradle and/or Maven
• Internet access or private artifact repository (for none mode)

Rust

Supported Build Modes

none, autobuild, manual

Default setup mode: none

Swift

Supported Build Modes

autobuild, manual (no none mode)

Default setup mode: autobuild

Runner requirement: macOS runners only. Not supported on Actions Runner Controller (ARC) — Linux only.

macOS runners are more expensive; consider scanning only the build step to optimize cost.

Multi-Language Matrix Examples

Mixed Build Modes

strategy:
  fail-fast: false
  matrix:
    include:
      - language: c-cpp
        build-mode: manual
      - language: csharp
        build-mode: autobuild
      - language: java-kotlin
        build-mode: none

Conditional Manual Build Steps

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

  - name: Initialize CodeQL
    uses: github/codeql-action/init@v4
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}

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

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

OS-Specific Runners

strategy:
  fail-fast: false
  matrix:
    include:
      - language: javascript-typescript
        build-mode: none
        runner: ubuntu-latest
      - language: swift
        build-mode: autobuild
        runner: macos-latest
      - language: csharp
        build-mode: autobuild
        runner: windows-latest

jobs:
  analyze:
    runs-on: ${{ matrix.runner }}

Hardware Requirements

Recommended Specifications (Self-Hosted Runners)

Performance Tips

• Use SSD storage for all codebase sizes
• Ensure enough disk space for checkout + build + CodeQL data
• Use --threads=0 to use all available CPU cores
• Enable dependency caching to reduce analysis time
• Consider none build mode where accuracy is acceptable — significantly faster than autobuild

Dependency Caching

Advanced Setup Workflows

- uses: github/codeql-action/init@v4
  with:
    languages: java-kotlin
    dependency-caching: true

Default setup on GitHub-hosted runners has caching enabled automatically.

CodeQL SARIF Output Reference

Detailed reference for the SARIF v2.1.0 output produced by CodeQL analysis. Use this when interpreting or processing CodeQL scan results.

About SARIF

SARIF (Static Analysis Results Interchange Format) is a standardized JSON format for representing static analysis tool output. CodeQL produces SARIF v2.1.0 (specification: sarifv2.1.0).

• Specification: OASIS SARIF v2.1.0
• Schema: sarif-schema-2.1.0.json
• Format type: sarifv2.1.0 (passed to --format flag)

Top-Level Structure

sarifLog Object

run Object

Tool Information

tool Object

Contains a single driver property.

toolComponent Object (Driver)

Rules

reportingDescriptor Object (Rule)

Severity Mapping

Results

result Object

By default, results are grouped by unique message format string and primary location. Two results at the same location with the same message appear as a single result. Disable grouping with --ungroup-results.

Fingerprints

partialFingerprints contains:

• primaryLocationLineHash — fingerprint based on the context of the primary location

Used by GitHub to track alerts across commits and avoid duplicate notifications.

Locations

location Object

physicalLocation Object

region Object

Two types of regions may be produced:

Line/Column Offset Regions:

Character Offset Regions:

Consumers should handle both region types robustly.

Artifacts

artifact Object

artifactLocation Object

Code Flows (Path Problems)

For queries of @kind path-problem, results include code flow information showing the data flow path.

codeFlow Object

threadFlow Object

threadFlowLocation Object

Automation Details

The category value from github/codeql-action/analyze appears as <run>.automationDetails.id in the SARIF output.

Example:

{
  "automationDetails": {
    "id": "/language:javascript-typescript"
  }
}

Key CLI Flags for SARIF

Third-Party SARIF Support

When uploading SARIF from non-CodeQL tools, ensure these properties are populated for best results on GitHub.

Recommended reportingDescriptor Properties

Source File Location Requirements

• Use relative paths (relative to repository root) when possible
• Absolute URIs are converted to relative using the source root
• Source root can be set via:
• checkout_path input to github/codeql-action/analyze
• checkout_uri parameter to SARIF upload API
• invocations[0].workingDirectory.uri in the SARIF file
• Consistent file paths are required across runs for fingerprint stability
• Symlinked files must use resolved (non-symlink) URIs

Fingerprint Requirements

• partialFingerprints with primaryLocationLineHash prevents duplicate alerts across commits
• CodeQL SARIF automatically includes fingerprints
• Third-party SARIF: the upload-sarif action computes fingerprints if missing
• API uploads without fingerprints may produce duplicate alerts

Upload Limits

File Size

• Maximum: 10 MB (gzip-compressed)
• If too large: reduce query scope, remove --sarif-add-file-contents, or split into multiple uploads

Object Count Limits

Files exceeding these limits are rejected. Split analysis across multiple SARIF uploads with different --sarif-category values.

Validation

Validate SARIF files before upload using the Microsoft SARIF validator.

Backwards Compatibility

• Fields marked "always generated" will never be removed in future versions
• Fields not always generated may change circumstances under which they appear
• New fields may be added without breaking changes
• Consumers should be robust to both presence and absence of optional fields

CodeQL Troubleshooting Reference

Comprehensive guide for diagnosing and resolving CodeQL analysis errors, SARIF upload issues, and common configuration problems.

Build and Analysis Errors

"No source code was seen during the build"

Cause: CodeQL extractor did not find any source files during database creation.

Solutions:

• Verify the --source-root points to the correct directory
• For compiled languages, ensure the build command actually compiles source files
• Check that autobuild is detecting the correct build system
• Switch from autobuild to manual build mode with explicit build commands
• Verify the language specified matches the actual source code language

Automatic Build Failed

Cause: autobuild could not detect or run the project's build system.

Solutions:

• Switch to build-mode: manual and provide explicit build commands
• Ensure all build dependencies are installed on the runner
• For C/C++: verify gcc, make, cmake, or msbuild are available
• For C#: verify .NET SDK or MSBuild is installed
• For Java: verify gradle or maven is installed
• Check the autobuild logs for the specific detection step that failed

C# Compiler Unexpectedly Failing

Cause: The CodeQL tracer injects compiler flags that may conflict with project configuration.

Details: CodeQL injects /p:EmitCompilerGeneratedFiles=true which can cause issues with:

• Legacy .NET Framework projects
• Projects using .sqlproj files

Solutions:

• Add <EmitCompilerGeneratedFiles>false</EmitCompilerGeneratedFiles> to problematic project files
• Use build-mode: none for C# if build accuracy is acceptable
• Exclude problematic projects from the CodeQL analysis

Analysis Takes Too Long

Cause: Large codebase, complex queries, or insufficient resources.

Solutions:

• Use build-mode: none where accuracy is acceptable (significantly faster)
• Enable dependency caching: dependency-caching: true
• Set timeout-minutes on the job to prevent hung workflows
• Use --threads=0 (CLI) to use all available CPU cores
• Reduce query scope: use default suite instead of security-and-quality
• For self-hosted runners, ensure hardware meets recommendations:
• Small (<100K LOC): 8 GB RAM, 2 cores
• Medium (100K–1M LOC): 16 GB RAM, 4–8 cores
• Large (>1M LOC): 64 GB RAM, 8 cores
• Configure larger GitHub-hosted runners if available
• Use paths in config file to limit analyzed directories

CodeQL Scanned Fewer Lines Than Expected

Cause: Build command didn't compile all source files, or build-mode: none missed generated code.

Solutions:

• Switch from none to autobuild or manual build mode
• Ensure the build command compiles the full codebase (not just a subset)
• Check the code scanning logs for extraction metrics:
• Lines of code in codebase (baseline)
• Lines of code extracted
• Lines excluding auto-generated files
• Verify language detection includes all expected languages

Kotlin Detected in No-Build Mode

Cause: Repository uses build-mode: none (Java only) but also contains Kotlin code.

Solutions:

• Disable default setup and re-enable it (switches to autobuild)
• Or switch to advanced setup with build-mode: autobuild for java-kotlin
• Kotlin requires a build to be analyzed; none mode only works for Java

Permission and Access Errors

Error: 403 "Resource not accessible by integration"

Cause: GITHUB_TOKEN lacks required permissions.

Solutions:

• Add explicit permissions to the workflow:

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

• For Dependabot PRs, use pull_request_target instead of pull_request
• Verify the repository has GitHub Code Security enabled (for private repos)

Cannot Enable CodeQL in a Private Repository

Cause: GitHub Code Security is not enabled.

Solution: Enable GitHub Code Security in repository Settings → Advanced Security.

Error: "GitHub Code Security or Advanced Security must be enabled"

Cause: Attempting to use code scanning on a private repo without the required license.

Solutions:

• Enable GitHub Code Security for the repository
• Contact organization admin to enable Advanced Security

Configuration Errors

Two CodeQL Workflows Running

Cause: Both default setup and a pre-existing codeql.yml workflow are active.

Solutions:

• Disable default setup if using advanced setup, or
• Delete the old workflow file if using default setup
• Check repository Settings → Advanced Security for active configurations

Some Languages Not Analyzed

Cause: Matrix configuration doesn't include all languages.

Solutions:

• Add missing languages to the matrix.include array
• Verify language identifiers are correct (e.g., javascript-typescript not just javascript)
• Check that each language has an appropriate build-mode

Unclear What Triggered a Workflow Run

Solutions:

• Check the tool status page in repository Settings → Advanced Security
• Review workflow run logs for trigger event details
• Look at the on: triggers in the workflow file

Error: "is not a .ql file, .qls file, a directory, or a query pack specification"

Cause: Invalid query or pack reference in the workflow.

Solutions:

• Verify query pack names and versions exist
• Use correct format: owner/pack-name@version or owner/pack-name:path/to/query.ql
• Run codeql resolve packs to verify available packs

Resource Errors

"Out of disk" or "Out of memory"

Cause: Runner lacks sufficient resources for the analysis.

Solutions:

• Use larger GitHub-hosted runners (if available)
• For self-hosted runners, increase RAM and disk (SSD with ≥14 GB)
• Reduce analysis scope with paths configuration
• Analyze fewer languages per job
• Use build-mode: none to reduce resource usage

Extraction Errors in Database

Cause: Some source files couldn't be processed by the CodeQL extractor.

Solutions:

• Check extraction metrics in workflow logs for error counts
• Enable debug logging for detailed extraction diagnostics
• Verify source files are syntactically valid
• Ensure all build dependencies are available

Logging and Debugging

Enable Debug Logging

To get more detailed diagnostic information:

GitHub Actions: 1. Re-run the workflow with debug logging enabled 2. In the workflow run, click "Re-run jobs" → "Enable debug logging"

CodeQL CLI:

codeql database create my-db \
  --language=javascript-typescript \
  --verbosity=progress++ \
  --logdir=codeql-logs

Verbosity levels: errors, warnings, progress, progress+, progress++, progress+++

Code Scanning Log Metrics

Workflow logs include summary metrics:

• Lines of code in codebase — baseline before extraction
• Lines of code in CodeQL database — extracted including external libraries
• Lines excluding auto-generated files — net analyzed code
• Extraction success/error/warning counts — per-file extraction results

Private Registry Diagnostics

For build-mode: none with private package registries:

• Check the "Setup proxy for registries" step in workflow logs
• Look for Credentials loaded for the following registries: message
• Verify organization-level private registry configuration
• Ensure internet access is available for dependency resolution

SARIF Upload Errors

SARIF File Too Large

Limit: 10 MB maximum (gzip-compressed).

Solutions:

• Focus on the most important query suites (use default instead of security-and-quality)
• Reduce the number of queries via configuration
• Split analysis into multiple jobs with separate SARIF uploads
• Remove --sarif-add-file-contents flag

SARIF Results Exceed Limits

GitHub enforces limits on SARIF data objects:

Solutions:

• Reduce query scope to focus on high-impact rules
• Split analysis across multiple SARIF uploads with different --sarif-category
• Disable noisy queries that produce many results

SARIF File Invalid

Solutions:

• Validate against the Microsoft SARIF validator
• Ensure version is "2.1.0" and $schema points to the correct schema
• Verify required properties (runs, tool.driver, results) are present

Upload Rejected: Default Setup Enabled

Cause: Cannot upload CodeQL-generated SARIF when default setup is active.

Solutions:

• Disable default setup before uploading via CLI/API
• Or switch to using default setup exclusively (no manual uploads)

Missing Authentication Token

Solutions:

• Set GITHUB_TOKEN environment variable with security-events: write scope
• Or use --github-auth-stdin to pipe the token
• For GitHub Actions: the token is automatically available via ${{ secrets.GITHUB_TOKEN }}

CodeQL Workflow Configuration Reference

Detailed reference for configuring CodeQL analysis via GitHub Actions workflows. This supplements the procedural guidance in SKILL.md.

Trigger Configuration

Push Trigger

Scan on every push to specified branches:

on:
  push:
    branches: [main, protected]

• Code scanning is triggered on every push to the listed branches
• The workflow must exist on the target branch for scanning to activate
• Results appear in the repository Security tab
• When push results map to an open PR, alerts also appear as PR annotations

Pull Request Trigger

Scan merge commits of pull requests:

on:
  pull_request:
    branches: [main]

• Scans the PR's merge commit (not the head commit) for more accurate results
• For private fork PRs, enable "Run workflows from fork pull requests" in repository settings
• Results appear as PR check annotations

Schedule Trigger

Periodic scans on the default branch:

on:
  schedule:
    - cron: '20 14 * * 1'  # Monday 14:20 UTC

• Only triggers if the workflow file exists on the default branch
• Catches newly discovered vulnerabilities even without active development

Merge Group Trigger

Required when using merge queues:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  merge_group:

Path Filtering

Control when the workflow runs based on changed files:

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

Or use paths to only trigger on specific directories:

on:
  pull_request:
    paths:
      - 'src/**'
      - 'apps/**'

Important: paths-ignore and paths control whether the workflow runs. When the workflow does run, it analyzes ALL changed files in the PR (including those matched by paths-ignore), unless files are excluded via the CodeQL configuration file's paths-ignore.

Workflow Dispatch (Manual Trigger)

on:
  workflow_dispatch:
    inputs:
      language:
        description: 'Language to analyze'
        required: true
        default: 'javascript-typescript'

Runner and OS Configuration

GitHub-Hosted Runners

jobs:
  analyze:
    runs-on: ubuntu-latest    # Also: windows-latest, macos-latest

• ubuntu-latest — most common, recommended for most languages
• macos-latest — required for Swift analysis
• windows-latest — required for some C/C++ and C# projects using MSBuild

Self-Hosted Runners

jobs:
  analyze:
    runs-on: [self-hosted, ubuntu-latest]

Requirements for self-hosted runners:

• Git must be in the PATH
• SSD with ≥14 GB disk space recommended
• See hardware requirements table in SKILL.md

Timeout Configuration

Prevent hung workflows:

jobs:
  analyze:
    timeout-minutes: 120

Language and Build Mode Matrix

Standard Matrix Pattern

strategy:
  fail-fast: false
  matrix:
    include:
      - language: javascript-typescript
        build-mode: none
      - language: python
        build-mode: none
      - language: java-kotlin
        build-mode: none
      - language: c-cpp
        build-mode: autobuild

Multi-Language Repository with Mixed Build Modes

strategy:
  fail-fast: false
  matrix:
    include:
      - language: c-cpp
        build-mode: manual
      - language: csharp
        build-mode: autobuild
      - language: java-kotlin
        build-mode: none

Build Mode Summary

CodeQL Database Location

Override the default database location:

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

• Default: ${{ github.runner_temp }}/codeql_databases
• Path must be writable and either not exist or be an empty directory
• On self-hosted runners, ensure cleanup between runs

Query Suites and Packs

Built-In Query Suites

- uses: github/codeql-action/init@v4
  with:
    queries: security-extended

Options:

• (default) — standard security queries
• security-extended — additional security queries with slightly higher false-positive rate
• security-and-quality — security plus code quality queries

Custom Query Packs

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

Model Packs

Extend CodeQL coverage for custom libraries/frameworks:

- uses: github/codeql-action/init@v4
  with:
    packs: my-org/my-model-pack

Analysis Category

Distinguish between multiple analyses for the same commit:

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

Monorepo Category Patterns

# Per language (default auto-generated pattern)
category: "/language:${{ matrix.language }}"

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

# Per app in monorepo
category: "/language:javascript-typescript/app:blog"

The category value appears as <run>.automationDetails.id in the SARIF output.

CodeQL Configuration File

Create .github/codeql/codeql-config.yml for advanced path and query configuration:

name: "CodeQL Configuration"

# Directories to scan
paths:
  - apps/
  - services/
  - packages/

# Directories to exclude
paths-ignore:
  - node_modules/
  - '**/test/**'
  - '**/fixtures/**'
  - '**/*.test.ts'

# Additional queries
queries:
  - uses: security-extended
  - uses: security-and-quality

# Custom query packs
packs:
  javascript-typescript:
    - codeql/javascript-queries
  python:
    - codeql/python-queries

Reference in the workflow:

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

Dependency Caching

Enable caching to speed up dependency resolution:

- uses: github/codeql-action/init@v4
  with:
    dependency-caching: true

Values:

• false / none / off — disabled (default for advanced setup)
• restore — only restore existing caches
• store — only store new caches
• true / full / on — restore and store caches

Default setup on GitHub-hosted runners has caching enabled automatically.

Alert Severity and Merge Protection

Use repository rulesets to block PRs based on code scanning alerts:

• A required tool finds an alert matching the defined severity threshold
• A required tool's analysis is still in progress
• A required tool is not configured for the repository

Configure via repository Settings → Rules → Rulesets → Code scanning.

Concurrency Control

Prevent duplicate workflow runs:

concurrency:
  group: codeql-${{ github.ref }}
  cancel-in-progress: true

Complete Workflow Example

name: "CodeQL Analysis"

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'

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

concurrency:
  group: codeql-${{ github.ref }}
  cancel-in-progress: true

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ${{ matrix.language == 'swift' && 'macos-latest' || 'ubuntu-latest' }}
    timeout-minutes: 120
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

    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

      - if: matrix.build-mode == 'manual'
        name: Manual Build
        run: |
          echo 'Replace with actual build commands'
          exit 1

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