Setting the file. One moment.
Subchapter 78.6
references/workflow-configuration.mdMarkdown9 KBView on GitHub
Detailed reference for configuring CodeQL analysis via GitHub Actions workflows. This supplements the procedural guidance in SKILL.md.
Scan on every push to specified branches:
on:
push:
branches: [main, protected]Scan merge commits of pull requests:
on:
pull_request:
branches: [main]Periodic scans on the default branch:
on:
schedule:
- cron: '20 14 * * 1' # Monday 14:20 UTCRequired when using merge queues:
on:
push:
branches: [main]
pull_request:
branches: [main]
merge_group: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-ignoreandpathscontrol whether the workflow runs. When the workflow does run, it analyzes ALL changed files in the PR (including those matched bypaths-ignore), unless files are excluded via the CodeQL configuration file’spaths-ignore.
on:
workflow_dispatch:
inputs:
language:
description: 'Language to analyze'
required: true
default: 'javascript-typescript'jobs:
analyze:
runs-on: ubuntu-latest # Also: windows-latest, macos-latestubuntu-latest — most common, recommended for most languagesmacos-latest — required for Swift analysiswindows-latest — required for some C/C++ and C# projects using MSBuildjobs:
analyze:
runs-on: [self-hosted, ubuntu-latest]Requirements for self-hosted runners:
Prevent hung workflows:
jobs:
analyze:
timeout-minutes: 120strategy:
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: autobuildstrategy:
fail-fast: false
matrix:
include:
- language: c-cpp
build-mode: manual
- language: csharp
build-mode: autobuild
- language: java-kotlin
build-mode: none| Language | none | autobuild | manual | Default Setup Mode |
|---|---|---|---|---|
| C/C++ | ✅ | ✅ | ✅ | none |
| C# | ✅ | ✅ | ✅ | none |
| Go | ❌ | ✅ | ✅ | autobuild |
| Java | ✅ | ✅ | ✅ | none |
| Kotlin | ❌ | ✅ | ✅ | autobuild |
| Python | ✅ | ❌ | ❌ | none |
| Ruby | ✅ | ❌ | ❌ | none |
| Rust | ✅ | ✅ | ✅ | none |
| Swift | ❌ | ✅ | ✅ | autobuild |
| JavaScript/TypeScript | ✅ | ❌ | ❌ | none |
| GitHub Actions | ✅ | ❌ | ❌ | none |
Override the default database location:
- uses: github/codeql-action/init@v4
with:
db-location: '${{ github.runner_temp }}/my_location'${{ github.runner_temp }}/codeql_databases- uses: github/codeql-action/init@v4
with:
queries: security-extendedOptions:
security-extended — additional security queries with slightly higher false-positive ratesecurity-and-quality — security plus code quality queries- 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.3Extend CodeQL coverage for custom libraries/frameworks:
- uses: github/codeql-action/init@v4
with:
packs: my-org/my-model-packDistinguish between multiple analyses for the same commit:
- uses: github/codeql-action/analyze@v4
with:
category: "/language:${{ matrix.language }}"# 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.
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-queriesReference in the workflow:
- uses: github/codeql-action/init@v4
with:
config-file: .github/codeql/codeql-config.ymlEnable caching to speed up dependency resolution:
- uses: github/codeql-action/init@v4
with:
dependency-caching: trueValues:
false / none / off — disabled (default for advanced setup)restore — only restore existing cachesstore — only store new cachestrue / full / on — restore and store cachesDefault setup on GitHub-hosted runners has caching enabled automatically.
Use repository rulesets to block PRs based on code scanning alerts:
Configure via repository Settings → Rules → Rulesets → Code scanning.
Prevent duplicate workflow runs:
concurrency:
group: codeql-${{ github.ref }}
cancel-in-progress: truename: "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 }}"