AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

codeql

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 need help with code scanning configuration, CodeQL workflow files, CodeQL CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--codeql at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

references/workflow-configuration.md

CodeQL Workflow Configuration Reference

Detailed reference for configuring CodeQL analysis via GitHub Actions workflows. This supplements the procedural guidance in SKILL.md.

Trigger Configuration

Push Trigger

Scan on every push to specified branches:

on:
  push:
    branches: [main, protected]
  • Code scanning is triggered on every push to the listed branches
  • The workflow must exist on the target branch for scanning to activate
  • Results appear in the repository Security tab
  • When push results map to an open PR, alerts also appear as PR annotations

Pull Request Trigger

Scan merge commits of pull requests:

on:
  pull_request:
    branches: [main]
  • Scans the PR's merge commit (not the head commit) for more accurate results
  • For private fork PRs, enable "Run workflows from fork pull requests" in repository settings
  • Results appear as PR check annotations

Schedule Trigger

Periodic scans on the default branch:

on:
  schedule:
    - cron: '20 14 * * 1'  # Monday 14:20 UTC
  • Only triggers if the workflow file exists on the default branch
  • Catches newly discovered vulnerabilities even without active development

Merge Group Trigger

Required when using merge queues:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  merge_group:

Path Filtering

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-ignore and paths control whether the workflow runs. When the workflow does run, it analyzes ALL changed files in the PR (including those matched by paths-ignore), unless files are excluded via the CodeQL configuration file's paths-ignore.

Workflow Dispatch (Manual Trigger)

on:
  workflow_dispatch:
    inputs:
      language:
        description: 'Language to analyze'
        required: true
        default: 'javascript-typescript'

Runner and OS Configuration

GitHub-Hosted Runners

jobs:
  analyze:
    runs-on: ubuntu-latest    # Also: windows-latest, macos-latest
  • ubuntu-latest — most common, recommended for most languages
  • macos-latest — required for Swift analysis
  • windows-latest — required for some C/C++ and C# projects using MSBuild

Self-Hosted Runners

jobs:
  analyze:
    runs-on: [self-hosted, ubuntu-latest]

Requirements for self-hosted runners:

  • Git must be in the PATH
  • SSD with ≥14 GB disk space recommended
  • See hardware requirements table in SKILL.md

Timeout Configuration

Prevent hung workflows:

jobs:
  analyze:
    timeout-minutes: 120

Language and Build Mode Matrix

Standard Matrix Pattern

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

Multi-Language Repository with Mixed Build Modes

strategy:
  fail-fast: false
  matrix:
    include:
      - language: c-cpp
        build-mode: manual
      - language: csharp
        build-mode: autobuild
      - language: java-kotlin
        build-mode: none

Build Mode Summary

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

CodeQL Database Location

Override the default database location:

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'
  • Default: ${{ github.runner_temp }}/codeql_databases
  • Path must be writable and either not exist or be an empty directory
  • On self-hosted runners, ensure cleanup between runs

Query Suites and Packs

Built-In Query Suites

- uses: github/codeql-action/init@v4
  with:
    queries: security-extended

Options:

  • (default) — standard security queries
  • security-extended — additional security queries with slightly higher false-positive rate
  • security-and-quality — security plus code quality queries

Custom Query Packs

- uses: github/codeql-action/init@v4
  with:
    packs: |
      codeql/javascript-queries:AlertSuppression.ql
      codeql/javascript-queries:~1.0.0
      my-org/[email protected]

Model Packs

Extend CodeQL coverage for custom libraries/frameworks:

- uses: github/codeql-action/init@v4
  with:
    packs: my-org/my-model-pack

Analysis Category

Distinguish between multiple analyses for the same commit:

- uses: github/codeql-action/analyze@v4
  with:
    category: "/language:${{ matrix.language }}"

Monorepo Category Patterns

# 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.

CodeQL Configuration File

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

Reference in the workflow:

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

Dependency Caching

Enable caching to speed up dependency resolution:

- uses: github/codeql-action/init@v4
  with:
    dependency-caching: true

Values:

  • false / none / off — disabled (default for advanced setup)
  • restore — only restore existing caches
  • store — only store new caches
  • true / full / on — restore and store caches

Default setup on GitHub-hosted runners has caching enabled automatically.

Alert Severity and Merge Protection

Use repository rulesets to block PRs based on code scanning alerts:

  • A required tool finds an alert matching the defined severity threshold
  • A required tool's analysis is still in progress
  • A required tool is not configured for the repository

Configure via repository Settings → Rules → Rulesets → Code scanning.

Concurrency Control

Prevent duplicate workflow runs:

concurrency:
  group: codeql-${{ github.ref }}
  cancel-in-progress: true

Complete Workflow Example

name: "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 }}"