Codeql

# 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 }}
      queri