/codeql

name: codeql
description: 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.

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 Code