CodeQL is GitHub’s static analysis engine for finding security vulnerabilities and coding errors. It extracts a relational representation of a codebase into a CodeQL database, then runs queries against that database. The representation includes syntax, types, control flow, and data flow, so queries can follow values across a program instead of matching text alone. CodeQL does not “understand the developer’s intent,” and a clean scan does not prove that an application is secure.
CodeQL complements, rather than replaces, manual practices such as using a secure code review checklist. GitHub’s CodeQL overview explains the analysis model in more detail.
Who should use CodeQL
CodeQL can be used during development, in continuous integration, while reviewing pull requests, and as part of static application security testing. Most teams can start with GitHub’s maintained queries; writing custom queries is optional.
Developers and reviewers can use code scanning alerts to inspect a finding, trace data-flow paths, and discuss or fix the affected code. Security specialists can develop custom queries for organization-specific vulnerability patterns or use CodeQL for variant analysis: finding other instances of a known vulnerability pattern.
How to use CodeQL
You do not need to install the CodeQL CLI or write queries to start using CodeQL on GitHub. There are three common setup options:
- Default setup: Enable CodeQL in the repository’s code security settings. GitHub detects supported languages, selects a build mode, and creates the scanning configuration. This is the recommended starting point for eligible repositories.
- Advanced setup: Commit a GitHub Actions workflow when you need control over languages, build steps, triggers, runners, query suites, or custom query packs.
- CodeQL CLI: Create and analyze CodeQL databases locally or in an external CI system. Results can be exported as SARIF and uploaded to GitHub code scanning.
GitHub documents the tradeoffs in About setup types for code scanning. Code scanning with CodeQL is available for public repositories on GitHub.com. Private and internal repositories need to be owned by an organization on GitHub Team or GitHub Enterprise with GitHub Code Security enabled.
On GitHub, an alert can include the affected location, severity, an explanation, data-flow paths when relevant, and guidance for fixing the problem. Copilot Autofix may also suggest a change for supported queries, but it does not produce a fix for every alert and generated fixes still require review and testing.
CodeQL during code review
With pull-request scanning enabled, findings can appear in the Code scanning results check and as annotations on changed lines. A finding is shown on a pull request only when all lines identified by the alert are present in the pull-request diff, so reviewers should not treat the annotations as a complete assessment of the repository.
Teams can configure which severity levels fail the check and can make the check required through branch protection. Reviewers should still validate whether a result is exploitable, whether a proposed fix is safe, and whether tests cover the change. See GitHub’s guide to triaging code scanning alerts in pull requests.
CodeQL integration and supported languages
CodeQL currently supports:
- C and C++
- C#
- Go
- Java and Kotlin
- JavaScript and TypeScript
- Python
- Ruby
- Rust
- Swift
- GitHub Actions workflows
CodeQL does not support every programming language; for example, PHP and Scala are not currently supported. Check GitHub’s current CodeQL language list before planning a rollout.
GitHub Actions is the most direct integration on GitHub. Advanced setup can also run on self-hosted runners, while the CodeQL CLI supports external CI systems.
Predefined queries
GitHub maintains two built-in query suites:
defaultprioritizes high-precision security queries and aims to keep false-positive results low.security-extendedincludes the default suite plus additional queries with slightly lower precision and severity, so it may find more issues but can also produce more false positives.
These queries are distributed in CodeQL query packs; they are not stored in the CodeQL database. The database contains the representation extracted from the codebase. GitHub maintains a current comparison of the built-in query suites.
Custom queries
The built-in suites do not cover every application-specific security rule. CodeQL’s QL language lets security specialists create queries for a known vulnerability pattern or an organization’s policies. Queries and libraries can be grouped and shared as CodeQL packs.
Use advanced setup to add custom query packs to GitHub code scanning. The CodeQL CLI and the CodeQL extension for Visual Studio Code are intended for developing and testing queries. Custom queries should be tested for precision before they become merge-blocking checks; a noisy rule can train reviewers to ignore useful alerts.
CodeQL example
CodeQL includes language-specific queries for several forms of cross-site scripting (XSS). An XSS query can track untrusted data from a source, such as an HTTP request, through the program to a sink that renders HTML or JavaScript. If the path does not pass through a recognized sanitizer, CodeQL may report it and show the data-flow path. The alert is a starting point for review: a reviewer still needs to confirm the trust boundary, framework behavior, and whether the data is safely encoded for the output context.
Summary
CodeQL is a query-based static analysis tool that integrates closely with GitHub code scanning. Default setup is the simplest route for most eligible repositories; advanced setup and the CLI provide control for custom builds, CI systems, and queries. During review, CodeQL is most useful as a consistent source of security findings and data-flow evidence, not as a substitute for human judgment or testing.
Learn more about the best automated code review tools and static application security testing.
