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:

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

Step 3: Configure Permissions

Set least-privilege permissions:

Step 4: Configure Language Matrix

Use a matrix strategy to analyze each language in parallel:

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

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:

To restrict analysis to specific directories, use a CodeQL configuration file (.github/codeql/codeql-config.yml):

Reference it in the workflow:

Step 7: Manual Build Steps (Compiled Languages)

If autobuild fails or custom build commands are needed:

Then add explicit build steps between init and analyze:

Core Workflow — CodeQL CLI

Step 1: Install the CodeQL CLI

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

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

For compiled languages, provide the build command via --command.

Step 3: Analyze the Database

Common query suites: <language>-code-scanning.qls, <language>-security-extended.qls, <language>-security-and-quality.qls.

Step 4: Upload Results to GitHub

Requires GITHUB_TOKEN environment variable with security-events: write permission.

CLI Server Mode

To avoid repeated JVM initialization when running multiple commands:

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

Creating Custom Query Packs

Use the CodeQL CLI to create and publish packs:

CodeQL Configuration File

For advanced query and path configuration, create .github/codeql/codeql-config.yml:

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:

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