Codeql

CodeQL code scanning

Set up, run, and troubleshoot CodeQL analysis through GitHub Actions or the CodeQL CLI, producing a working workflow, local commands, SARIF upload path, and alert triage guidance.

When to invoke

• "Create a CodeQL workflow for this repository."
• "Should we use default setup or advanced setup for code scanning?"
• "Run CodeQL CLI locally and upload SARIF."
• "Troubleshoot this CodeQL build-mode failure."
• "Configure CodeQL for a monorepo with custom query packs."

Prerequisites and context

• GitHub code scanning must be available for the repository.
• Advanced setup uses .github/workflows/codeql.yml and may use .github/codeql/codeql-config.yml.
• CLI uploads require GITHUB_TOKEN with security-events: write plus repository, ref, and commit metadata.
• Use the CodeQL bundle from https://github.com/github/codeql-action/releases, not a standalone CLI download, so bundled queries and precompiled packs match the CLI.

Supported languages

GitHub Actions workflow

1. Choose setup type.
   • Default setup: enable in repository Settings → Advanced Security → CodeQL analysis. Best for fast onboarding; uses none build mode for most languages.
   • Advanced setup: commit .github/workflows/codeql.yml for full control over triggers, build modes, query suites, path filters, custom packs, and monorepos. Disable default setup before switching to advanced.
2. Configure triggers. Use push, pull_request, schedule, and merge_group when merge queues are enabled. paths-ignore controls whether the workflow runs, not which files are analyzed.
3. Set least-privilege permissions: security-events: write, contents: read, and actions: read for private repositories using codeql-action.
4. Use a matrix with fail-fast: false and one row per language/build-mode pair.
5. Initialize, build if needed, analyze, and set a unique category such as /language:${{ matrix.language }} or /language:${{ matrix.language }}/component:frontend.

name: CodeQL
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'
  merge_group:

permissions:
  security-events: write
  contents: read
  actions: read

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
    steps:
      - uses: actions/checkout@v4
      - 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'
        run: |
          make bootstrap
          make release
      - uses: github/codeql-action/analyze@v4
        with:
          category: "/language:${{ matrix.language }}"

Configuration choices

paths:
  - apps/
  - services/
paths-ignore:
  - '**/test/**'
  - node_modules/
queries:
  - uses: security-extended
packs:
  javascript-typescript:
    - my-org/my-custom-queries

CodeQL CLI workflow

export PATH="$HOME/codeql:$PATH"
codeql resolve packs
codeql resolve languages

codeql database create codeql-db \
  --language=javascript-typescript \
  --source-root=src

codeql database create codeql-dbs \
  --db-cluster \
  --language=java,python \
  --command=./build.sh \
  --source-root=src

codeql database analyze codeql-db \
  javascript-code-scanning.qls \
  --format=sarif-latest \
  --sarif-category=javascript \
  --output=results.sarif

codeql github upload-results \
  --repository=owner/repo \
  --ref=refs/heads/main \
  --commit=<commit-sha> \
  --sarif=results.sarif

codeql execute cli-server

Common suites are <language>-code-scanning.qls, <language>-security-extended.qls, and <language>-security-and-quality.qls. Use --command for compiled-language database creation. Use --verbosity=progress++ and --logdir=codeql-logs for local debug logs.

Alerts, logs, and limits

Troubleshooting

Progressive disclosure and bundled resources

Read bundled references only when the main skill is insufficient for the current task.

• references/workflow-configuration.md: triggers, schedules, paths-ignore, db-location, model packs, alert severity, merge protection, concurrency, config files.
• references/cli-commands.md: database create, database analyze, upload-results, resolve packs, cli-server, installation, CI integration.
• references/sarif-output.md: sarifLog, result, location, region, codeFlow, fingerprint, suppression, upload limits, third-party support, precision, security-severity.
• references/compiled-languages.md: C/C++, C#, Java, Go, Rust, Swift, autobuild, build-mode, hardware, dependency caching.
• references/troubleshooting.md: 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: severity, security severity, CVSS, GitHub Copilot Autofix, dismissals, triage, PR alerts, data flow, merge protection, REST API.

Technical index

Preserve these CodeQL reference search terms, commands, and troubleshooting labels when narrowing the workflow: codeql.yml, codeql database create, github upload-results, config-file, packs:, my-org/my-queries, my-queries, per-component, per-language, documentation-only, auto-generated, re-run, re-enable, disk/memory, branches, trigger, analyze, installation, CI integration, concurrency, config file, dependency caching, hardware, model packs, merge protection, alert severity, security severity, severity, triage, dismiss, PR alerts, data flow, REST API, Copilot Autofix, C# compiler, Kotlin, debug logging, extraction errors, errors/warnings**, fewer lines, no source code, out of disk, out of memory, analysis too long, SARIF upload, SARIF limits, and upload limits.

Output template

## CodeQL setup result

**Status:** configured | commands provided | blocked
**Mode:** default setup | advanced setup | CLI
**Languages:** <language identifiers>

### Files or commands
- `.github/workflows/codeql.yml`: <created/updated/not needed>
- `.github/codeql/codeql-config.yml`: <created/updated/not needed>
- CLI command: `<codeql ...>`

### Key settings
| Setting | Value | Reason |
| --- | --- | --- |
| `build-mode` | `<none/autobuild/manual>` | <why> |
| `queries` | `<suite or packs>` | <why> |
| `category` | `<category>` | <why> |

### Validation
- Workflow syntax: <checked/not checked>
- CodeQL init/analyze or CLI run: <pass/fail/not run>
- SARIF upload readiness: <pass/fail/not applicable>

Quality gate

• Setup type is explicit: default, advanced, or CLI.
• Language identifiers use CodeQL-supported names or documented alternatives.
• Compiled languages have a deliberate build-mode and manual commands when needed.
• Workflow permissions include only required permissions, especially security-events: write.
• Query suites, packs, path filters, dependency caching, and categories are justified.
• CLI instructions use the CodeQL bundle, create a database, analyze it, and upload SARIF only with a valid GITHUB_TOKEN.
• Troubleshooting advice maps to the observed failure rather than generic rebuild advice.

References

• CodeQL Action releases