Comprehensive guide for setting up and configuring CodeQL code scanning via GitHub Actions workflows and the CodeQL CLI. This skill should be used when users…
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 APIdon't have the plugin yet? install it then click "run inline in claude" again.
added explicit inputs (cli, build tools, db location, suite files, external connections), numbered 8-step procedure with input/output per step, decision logic for unclear builds/arm64 failures/zero findings, detailed output contract with file locations and invariants, outcome signals with verification method.
run interprocedural security vulnerability scanning across Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, and Swift codebases using CodeQL's data flow analysis. use this skill when you need to find SQL injection, command injection, path traversal, XSS, or other taint-based vulnerabilities that span multiple functions or modules. the skill enforces database quality checks, custom data extensions for project-specific APIs, and explicit query suite references to avoid silent filtering and false negatives.
codeql cli
codeql --versionsource code repository
language-specific build tools
codeql database location
codeql database create will write (typically ./codeql-db-<lang>)query suite files
{baseDir}/queries/ or {baseDir}/references/security-and-quality.qls instead of codeql/python-queriesexternal connections
GITHUB_TOKEN)SARIF_ENDPOINT)reference materials
{baseDir}/workflows/ (e.g., build-analyze-python.sh){baseDir}/references/select language and confirm build method
codeql resolve languages and language-specific docscreate codeql database
codeql database create --language=<lang> --source-root=<path> --build-mode=auto <dbpath>--build-mode=none or use rosetta<dbpath>--build-mode=none (source-based extraction only; some languages less precise)assess database quality
codeql database info <dbpath> and codeql database analyze <dbpath> --format=json --output=quality.json codeql/python-queries (substitute language)create data extensions for custom code paths
{baseDir}/references/data-extensions/codeql database index-files <dbpath> --additional-packs=<ext-pack-dir>generate explicit query suite file
{baseDir}/queries/security-and-quality.qlscodeql-python/ql/src/Security/CWE-089/SqlInjection.ql)codeql/python-queries) directly to analyze; packs apply hidden defaultSuiteFile filters- query: Security/CWE-089/SqlInjection.ql
- query: Security/CWE-078/CommandInjection.ql
run analysis with explicit suite reference
codeql database analyze <dbpath> --format=sarif-latest --output=results.sarif <suite-file.qls>investigate zero findings
--verbose flagprocess and deliver sarif results
curl -X POST <SARIF_ENDPOINT> -d @results.sarifif build method is unclear:
codeql resolve languages and consult language-specific extractor docs--build-mode=none (source-only extraction; less precise but will complete)if database build fails with exit 137 on arm64 macos:
arch -x86_64 codeql database create ...--build-mode=noneif database quality check fails (low file count or many extractor errors):
if zero findings after analysis:
--verbose to confirm suite applied correctlyif custom data extensions needed:
if sarif upload fails (network timeout, auth error, endpoint down):
codeql database
<dbpath> specified in step 2quality report
quality.json from step 3data extensions (if applicable)
{baseDir}/references/data-extensions/ or custom pack directoryquery suite file
{baseDir}/queries/security-and-quality.qlssarif results
results.sarif from step 6investigation summary (if zero findings)
investigation.txt