SKILL.md

CodeQL Code Scanning

Name: codeql
Author: github

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

csharp

—

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

codeql