GitHub Actions CodeQL Scanning

CodeQL is GitHub's code analysis engine. It reads your source code like a database and searches for patterns that signal security flaws, such as SQL injection or unsafe file handling. A workflow runs the scan automatically and reports findings inside GitHub.

CodeQL in Simple Words

Imagine a proofreader who checks a long book for dangerous typos, such as a wrong dosage in a medical guide. The proofreader does not run the book. The proofreader reads every page and flags suspicious spots. CodeQL does that for code and flags risky lines without running the program.

How the Scan Works

+-------------+     +----------------+     +---------------+     +--------------+
| Source code | --> | CodeQL builds  | --> | Queries look  | --> | Alerts appear|
|             |     | a database     |     | for known     |     | in Security  |
|             |     | from the code  |     | flaw patterns |     | tab          |
+-------------+     +----------------+     +---------------+     +--------------+

Supported Languages

Language Group	CodeQL Identifier
JavaScript and TypeScript	javascript-typescript
Python	python
Java and Kotlin	java-kotlin
C and C++	c-cpp
C#	csharp
Go	go
Ruby	ruby
Swift	swift
GitHub Actions workflows	actions

The list grows over time. Check the CodeQL documentation for the current set.

The Easy Way: Default Setup

Open Settings, choose Code security, find Code scanning, and select Set up with Default. GitHub detects your languages and creates the scan with no workflow file. Default setup suits most projects.

The Flexible Way: Advanced Workflow

A workflow file gives full control over triggers, languages, and build steps.

name: CodeQL

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  schedule:
    - cron: "0 3 * * 1"

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    strategy:
      fail-fast: false
      matrix:
        language: [ "javascript-typescript", "python" ]
    steps:
      - uses: actions/checkout@v4

      - name: Start CodeQL
        uses: github/codeql-action/init@v4
        with:
          languages: ${{ matrix.language }}

      - name: Build if needed
        uses: github/codeql-action/autobuild@v4

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

Action version tags change over time. Confirm the latest CodeQL action version on its repository page before use.

Step-by-Step Meaning

Init

The init step installs CodeQL and prepares the database for the chosen language.

Autobuild

Compiled languages such as Java and C++ need a build so CodeQL can observe the code. Autobuild guesses the build command. Interpreted languages such as Python and JavaScript skip this step.

Analyze

The analyze step runs the queries and uploads results. The security-events: write permission allows the upload.

Matrix Strategy

The matrix runs one job per language, so each result stays separate and easy to read.

Three Triggers, Three Purposes

push to main   --> scans the code that just landed
pull_request   --> scans changes before they merge
schedule       --> rescans old code when new queries arrive

The scheduled run matters because researchers publish new queries regularly. Code that passed last month may show a new alert today.

Reading the Results

Open the Security tab and choose Code scanning. Each alert lists the file, the line, the rule name, and a clear explanation. Select an alert to see the path that untrusted data takes through the code. Pull requests show alerts as annotations on the changed lines.

Handling Alerts

Action	When to Use
Fix the code	The alert points to a real flaw
Dismiss as false positive	The pattern looks risky but the code is safe
Dismiss as used in tests	The flaw exists only in test code

Availability

Code scanning is free for public repositories. Private repositories need GitHub's paid code security product. Check the current plans page for details.