What Is CodeQL? How GitHub's Query-Based Code Scanning Works (2026)

What is CodeQL?

CodeQL is a static analysis engine, built by GitHub, that treats your codebase as a database you can run queries against. Most scanners look at code as text and hunt for suspicious patterns with regular expressions. CodeQL does something more ambitious - it compiles your source into a relational database that captures the code’s structure, control flow, and data flow, and then lets you interrogate that database with a purpose-built query language called QL. Asking “is there any path where user input reaches a SQL statement without being sanitized?” becomes a literal query, and the engine finds every such path across the whole program.

That reframing is the whole idea. Once code is a database, finding a vulnerability is a search problem rather than a guessing game. A well-written query can trace tainted data from an HTTP request, through half a dozen function calls and files, into a dangerous sink, and report the exact path. This is why CodeQL is strong at the vulnerability classes that defeat pattern-only tools - injection, unsafe deserialization, path traversal - the kinds of flaws catalogued in the OWASP Top 10. It sits firmly in the SAST category of security tooling.

How CodeQL works, step by step

CodeQL analysis happens in three distinct phases. Understanding them explains both its power and its cost.

1. Database creation. CodeQL extracts a database from your source. For interpreted languages like Python or JavaScript it reads the code directly. For compiled languages like Java or C++ it must observe the build - it watches the compiler run so it can capture exactly what gets compiled and how. This build dependency is why CodeQL setup is heavier than a text scanner.
2. Query execution. The engine runs QL queries against that database. Each query is a logical program that describes a pattern of interest - a source of untrusted data, a dangerous sink, and the absence of a sanitizer between them. GitHub maintains extensive open-source query packs, so you inherit thousands of expert-written security queries without authoring any yourself.
3. Results as alerts. Matches become code scanning alerts, each with the dataflow path that produced it, mapped to a CWE identifier so you know the weakness class. In GitHub, these appear in the Security tab and can annotate the pull request directly.

The signature capability here is taint tracking - following untrusted data as it flows through the program. A pattern matcher sees a single line; CodeQL sees the journey. That whole-program dataflow model is what lets it catch a vulnerability whose source and sink live in completely different files.

The QL query language

QL is a declarative, logic-based query language. You do not write step-by-step instructions; you describe the shape of what you are looking for and let the engine find every instance. An illustrative security query reads roughly like this:

// Illustrative - find user input flowing into a SQL query
import python
import semmle.python.dataflow.new.TaintTracking

from RemoteFlowSource source, SqlExecution sink
where TaintTracking::localTaint(source, sink)
select sink, "Untrusted data reaches a SQL query from $@.", source, "here"

You rarely need to write queries like this. Most teams run the standard packs. But the option matters - when your codebase has a custom sink or a project-specific dangerous API, you can extend the libraries to teach CodeQL about it, which is how large security teams tune the tool to their own frameworks.

Enabling CodeQL with GitHub code scanning

For the majority of users, CodeQL is not a standalone tool you install - it is the engine behind GitHub code scanning. Turning it on is a workflow decision, not a research project.

• Default setup is the fast path. In a repository’s Security settings, enable code scanning with CodeQL default setup and GitHub configures a workflow that scans on push and pull request automatically, choosing sensible query suites for your detected languages.
• Advanced setup gives you a codeql-analysis.yml GitHub Actions workflow you control - useful when you need custom build steps, specific query packs, or a particular schedule. If you already run AI code review in GitHub Actions, CodeQL slots into the same pipeline.
• Pull request integration is where it earns its keep. New alerts introduced by a PR are posted as checks, so a vulnerability is caught before merge rather than in a later audit - the essence of shift-left security.

On cost - CodeQL code scanning is free for public repositories. For private repositories it is part of GitHub Advanced Security, a paid add-on. That licensing reality is often the deciding factor between CodeQL and an alternative.

How CodeQL compares to other SAST tools

CodeQL is powerful but opinionated, and it is not the only serious option. The right choice depends on your ecosystem, your appetite for setup, and how much analytical depth you actually need.

Semgrep is the most common alternative and the clearest contrast. Semgrep matches patterns against a lighter syntactic and dataflow model, which makes its rules dramatically faster to write - they look almost like the code they match - and its scans quicker. CodeQL goes deeper with full whole-program dataflow but pays for it in setup and query complexity. Semgrep also runs anywhere with a free open-source engine, while CodeQL is happiest inside GitHub. Our head-to-head Semgrep vs CodeQL guide breaks down exactly when each wins.

Snyk Code takes a third path - AI-assisted SAST through its DeepCode engine, with auto-fix suggestions and tight coupling to dependency scanning. It trades CodeQL’s query flexibility for a more turnkey, developer-first experience. See Snyk vs CodeQL for the comparison and our best SAST tools roundup for the wider field.

None of these are mutually exclusive with an AI reviewer. CodeRabbit and similar tools catch a different class of issue - logic bugs, missing tests, review-level concerns - and pair well with a dedicated SAST engine running underneath.

In short - reach for CodeQL when you live in GitHub, need deep dataflow analysis, and can absorb the setup; reach for Semgrep when you want fast, portable, easy-to-write rules.

When CodeQL is the right tool

CodeQL is an excellent fit when three things are true - your code is on GitHub, you have a real need for deep security analysis rather than surface linting, and you either work in the open (where it is free) or already pay for Advanced Security. Security-conscious teams building anything that handles untrusted input benefit most, because taint tracking is where CodeQL genuinely outclasses lighter tools.

It is a weaker fit when you are outside GitHub, when your team lacks the appetite to manage build-integrated scanning, or when you mainly want fast, low-friction checks in the pull request. In those cases a portable tool like Semgrep, or an AI reviewer for logic-level feedback, often delivers more value per hour of setup.

Conclusion

CodeQL’s core insight is simple and powerful - turn code into a queryable database and finding vulnerabilities becomes a search, complete with the exact dataflow path from untrusted source to dangerous sink. Most teams consume it through GitHub code scanning without ever writing a query, getting deep taint-tracking security analysis on every pull request. It is free for open source and part of GitHub Advanced Security for private repos. Weigh it against faster, more portable tools like Semgrep and turnkey options like Snyk Code, pick based on your ecosystem and your need for depth, and run it in the pull request where a caught vulnerability is still cheap to fix.

Further reading

• Semgrep vs CodeQL
• Snyk vs CodeQL
• Best SAST Tools in 2026
• Shift-Left Security Explained

Further Reading

• CodeRabbit Security: How AI Detects Vulnerabilities