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:

yaml

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:

yaml

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:

yaml

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:

yaml

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

yaml

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:

yaml

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

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

.github/codeql/codeql-config.yml

yaml

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

Reference it in the workflow:

yaml

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

Step 7: Manual Build Steps (Compiled Languages)

autobuild

fails or custom build commands are needed:

yaml

- language: c-cpp
  build-mode: manual

Then add explicit build steps between

init

and

analyze

yaml

- 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):

bash

# 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

bash

# 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

bash

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

bash

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:

bash

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

yaml

- 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:

bash

# 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

yaml

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:

yaml

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

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

NPX Install

Tags

SKILL.md Content

CodeQL Code Scanning

When to Use This Skill

Supported Languages

Core Workflow — GitHub Actions

Step 1: Choose Setup Type

Step 2: Configure Workflow Triggers

Step 3: Configure Permissions

Step 4: Configure Language Matrix

Step 5: Configure CodeQL Init and Analysis

Step 6: Monorepo Configuration

Step 7: Manual Build Steps (Compiled Languages)

Core Workflow — CodeQL CLI

Step 1: Install the CodeQL CLI

Step 2: Create a CodeQL Database

Step 3: Analyze the Database

Step 4: Upload Results to GitHub

CLI Server Mode

Alert Management

Severity Levels

Copilot Autofix

Alert Triage in PRs

Custom Queries and Packs

Using Custom Query Packs

Creating Custom Query Packs

CodeQL Configuration File

Code Scanning Logs

Summary Metrics

Debug Logging

Troubleshooting

Common Issues

Hardware Requirements (Self-Hosted Runners)

Action Versioning

Reference Files