Wiki · Concept · Last reviewed June 25, 2026

CodeQL

CodeQL is GitHub's semantic code-analysis language and toolchain for representing source code as data, running security queries, and producing evidence for code-scanning workflows.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: CodeQL, code scanning, static analysis, AI coding agents, security evidence

Definition

CodeQL is a language and toolchain for code analysis maintained by GitHub. The central idea is that a repository can be converted into a CodeQL database and then queried as data. GitHub Docs describes it as the code analysis engine used to automate security checks and display results as code scanning alerts.

That makes CodeQL more than a linter. A query can describe a vulnerability pattern, data-flow relationship, API misuse, unsafe source-to-sink path, or maintainability issue. The result is not a proof that the program is secure; it is a structured claim that a particular pattern appears in a particular codebase under a particular query pack and tool version.

How It Works

A CodeQL workflow usually has three parts. First, CodeQL creates a database representation of the target code. Second, it runs CodeQL queries against that database. Third, it emits results that can be shown in GitHub code scanning or, when using the CLI, summarized in SARIF for upload or archival review.

GitHub documents three broad setup paths for code scanning with CodeQL: default setup in GitHub, an advanced workflow using github/codeql-action, or direct use of the CodeQL CLI in an external continuous integration system. The CLI documentation describes commands for database creation, database analysis, and upload of resulting SARIF files to GitHub.

The standard libraries and queries are developed in the open source github/codeql repository. CodeQL documentation says queries can be used for security, correctness, maintainability, and readability issues, with alert queries pointing to code locations and path queries describing flows between sources and sinks.

Agent Context

AI coding agents change the review environment around CodeQL. The scanner is no longer only checking human-authored pull requests; it may be checking patches generated in minutes by an automated assistant. In that setting, CodeQL gives reviewers a stable counterweight to fluent code generation: a reproducible query, a database, a result location, and a rerun after the patch changes.

The strongest pattern is not "ask the model to fix the warning." It is to preserve the original finding, feed the agent the smallest relevant context, require a patch that explains the root cause, rerun CodeQL, and compare the result set. If a finding disappears because the code was genuinely changed, that is different from a warning suppressed by annotation, unreachable test harness, or a framework model the query does not understand.

CodeQL is also useful in agent evaluation. A benchmark can ask whether an agent fixes known vulnerable patterns without breaking behavior, introducing new alerts, or hiding the scanner signal. The query output becomes one part of the evidence, not the whole judgment.

Governance Use

A governance-grade CodeQL record should include the commit SHA, repository, language, CodeQL CLI or action version, query suite or query pack version, database creation command, build command for compiled languages, SARIF artifact, alert identifiers, review decision, suppression rationale, and rerun result. For AI-assisted changes, it should also record the agent or tool that proposed the patch, the task prompt or ticket, the human approver, and any policy exception.

CodeQL belongs near Common Weakness Enumeration, CVE, OSV, OpenSSF Scorecard, and AI Audit Trails. It can discover weakness patterns, but it is not a vulnerability registry, severity framework, package advisory database, or institutional approval record.

Limits

CodeQL coverage depends on the supported language, extractor behavior, framework modeling, build configuration, and query pack. GitHub's supported-languages documentation is explicit about current language and compiler support, and its framework support list changes with the current CodeQL libraries and query packs. Unsupported languages or misconfigured builds can produce incomplete analysis.

Static analysis also has ordinary limits. CodeQL can miss runtime conditions, environment-specific configuration flaws, authorization policy errors, generated-code behavior, supply-chain compromise, or vulnerabilities outside the modeled data flow. It can also raise findings that require human triage. An AI repair loop should treat a clean CodeQL run as evidence, not as a release certificate.

Source Discipline

Claims about CodeQL should cite CodeQL documentation, GitHub Docs for code scanning behavior, and the github/codeql repository for the standard libraries and queries. A real audit note should state the date checked, CLI or action version, query pack version, supported language, build mode, and whether results were uploaded to GitHub or preserved independently as SARIF.

Spiralist Reading

Spiralism reads CodeQL as disciplined suspicion made executable. It turns a security researcher's question into a repeatable search over code, then leaves a record that humans can dispute. The scanner is not an oracle; it is a way to keep concern from evaporating when code moves quickly.

For agentic software work, that discipline matters. A model can sound certain while changing a dangerous line. CodeQL asks a colder question: under this query, in this database, at this commit, what pattern is still present?

Sources

Return to Wiki