What it is: Code scanning is a GitHub feature that automatically analyzes a project’s source code to find security vulnerabilities and coding errors, without anyone needing to actually run the software. CodeQL is the specific analysis engine GitHub built to power this — a tool that treats source code almost like a searchable database, letting it ask precise questions about how data moves through a program to uncover genuinely dangerous patterns.

Why it exists: Many serious security vulnerabilities aren’t obvious typos or crashes — they’re subtle patterns in how a program handles data, such as taking text directly from a user and passing it, unchecked, into a database command. A human reviewer, even a careful one, can easily miss these patterns buried across a large codebase, especially when the dangerous data has passed through several functions before reaching the risky point. Code scanning exists to catch exactly this category of subtle, easy-to-miss vulnerability automatically, every time code changes.

Where it’s used: Code scanning with CodeQL is used across projects handling anything sensitive — web applications processing user data, backend services handling authentication, and any software where a security flaw could have real consequences. It integrates directly into the same pull-request workflow covered in a related guide on code review, surfacing findings right where developers are already working.

Practical example: A web application accepts a search term typed by a visitor and uses it to build a database query. If that search term is inserted directly into the query without being properly handled, a malicious visitor could type something crafted to manipulate the database itself — a well-known category of vulnerability called SQL injection. CodeQL can trace this exact path, from the point user input enters the program to the point it reaches the database command, and flag it automatically before the code is even merged.

For decades, a huge share of serious security breaches have traced back to the same handful of well-understood vulnerability patterns, appearing again and again across different projects, languages, and companies — not because developers are careless, but because these patterns are genuinely easy to introduce accidentally, especially in large, fast-moving codebases with many contributors. Manual code review, while valuable, is inherently limited by human attention and time: a reviewer skimming a large pull request can reasonably catch an obviously wrong calculation, but tracing exactly how one specific piece of untrusted data flows through a dozen intervening functions before reaching a dangerous operation is a very different, much more exhausting kind of checking.

CodeQL was developed specifically to make this kind of deep, pattern-based tracing automatic and repeatable. Rather than relying on any single person remembering every known vulnerability pattern and manually checking for each one in every review, CodeQL encodes that knowledge into reusable, precise queries that run consistently, every time, across the entire codebase.

The core problem code scanning solves: well-known, dangerous coding patterns keep slipping into real software because reliably tracing them by hand, across a large and constantly changing codebase, exceeds what manual review alone can consistently catch. Automated, repeatable analysis closes that gap.

CodeQL’s central idea is treating source code as data that can be queried, rather than just text to be read line by line. When CodeQL analyzes a codebase, it first builds what’s essentially a detailed database representing the code’s structure — every function, every variable, every place data is assigned, passed along, or used. This database captures not just what the code looks like, but how its pieces actually relate to and affect each other.

Security researchers and GitHub’s own team then write queries — precise, reusable questions — against that database, describing exactly what a specific vulnerability pattern looks like structurally. A query might, in effect, ask: “is there any path where data starts at a point where a user can control it, and ends at a database command, without passing through any step that properly checks or cleans it along the way?” Running that query against the database representation of a real codebase finds every place, if any, where that exact dangerous pattern actually occurs.

This approach is what allows CodeQL to catch vulnerabilities that depend on tracing data across multiple functions and files — something a simple, surface-level text search could never reliably do, since the dangerous pattern only becomes visible once you follow the full path data actually takes through the program.

flowchart LR
    A["Code scanning is triggered (push or pull request)"] --> B["CodeQL builds a database representing the code"]
    B --> C["Security queries run against that database"]
    C --> D{"Any dangerous patterns found?"}
    D -->|No| E["Scan passes, no alerts raised"]
    D -->|Yes| F["Alerts created, shown on the pull request or Security tab"]
    F --> G["Developer reviews, fixes, or dismisses each alert"]
    

Step by step, in plain language: first, code scanning is triggered — commonly configured to run automatically on every push and every pull request, similar to how automated tests run, as covered in a related guide on GitHub Actions. Second, CodeQL analyzes the relevant source code and builds its structured database representation, capturing the code’s logic and data relationships. Third, a curated set of security queries — each targeting a specific, well-known vulnerability pattern — runs against that database. Fourth, if any query finds a genuine match, CodeQL creates an alert describing exactly what was found: the type of vulnerability, the specific file and line involved, and, crucially, the full path the dangerous data takes through the code, from where it enters to where it becomes risky. Finally, these alerts appear directly on the relevant pull request, alongside a dedicated Security tab for the whole repository, where a developer can review each one, fix the underlying issue, or — if the alert turns out not to genuinely apply in this specific case — formally dismiss it with a documented reason.

Notice how this entire cycle happens before the change is ever merged into the shared branch — the vulnerability is caught, investigated, and fixed within the normal pull-request process, rather than requiring a separate, after-the-fact security review process.

Code scanning (CodeQL), the subject of this guide, analyzes the code your own team actually wrote, looking for vulnerability patterns in your own logic. Dependency scanning (sometimes discussed alongside a feature called Dependabot) is different — it doesn’t analyze your code’s logic at all, but instead checks the external libraries and packages your project relies on against a database of already-known, publicly disclosed vulnerabilities in those specific libraries. Secret scanning is different again — it searches your code and commit history for accidentally committed sensitive values, like API keys or passwords, rather than analyzing logic or checking external libraries at all.

CodeQL’s queries are organized into groups called query suites, letting a team choose how broad or how deep their scanning should be. A smaller, default suite focuses on the most severe, highest-confidence vulnerability patterns — the ones most likely to represent a genuine, serious problem, with relatively few false alarms. Broader, more extensive suites include additional checks for less severe issues, or patterns that require more careful human judgment to confirm as genuinely problematic, at the cost of a higher volume of alerts to review.

Choosing the right suite is itself a trade-off worth understanding, covered more fully in Chapter 9 — broader scanning finds more, but also demands more reviewing time from the team to sort genuine findings from noise.

When code scanning finds a genuine issue, the expected response is usually to fix the underlying code so the dangerous data-flow pattern no longer exists — properly validating or cleaning risky input before it reaches a sensitive operation, for example. Once the fix is committed, the next scan automatically confirms the pattern is gone and closes the alert on its own, with no manual bookkeeping required.

Sometimes, though, an alert doesn’t represent a genuine, exploitable problem in its specific context — perhaps the “risky” data is actually already fully trusted for a documented reason specific to that code. For these cases, a developer can formally dismiss the alert, selecting a reason (such as “used in tests” or “false positive”) and optionally leaving a comment explaining the judgment call, creating a permanent, visible record of that decision for anyone who reviews the code later.

The core trade-off to internalize: code scanning trades some reviewing effort — investigating and occasionally dismissing alerts — for consistent, automated coverage of well-known vulnerability patterns across an entire codebase, every single time it changes. It’s a powerful complement to human code review, not a full replacement for it.

It’s worth remembering that dismissing an alert, as covered in Chapter 8, is a genuine security decision, not just a way to clear a notification — a dismissed alert that was actually a real, exploitable issue is just as dangerous as never having scanned at all, arguably more so, since it creates false confidence that the code was checked and cleared. Teams benefit from treating alert dismissal with the same care and, ideally, the same review process as any other security-relevant decision.

Finally, because code scanning is itself configured through files inside the repository — much like the workflow files covered in a related guide on GitHub Actions — changes to that configuration deserve the same review scrutiny as any other security-relevant change, since someone with the ability to quietly weaken or disable scanning could undermine the entire protection it provides without it being immediately obvious.

The Every-Pull-Request Pattern runs code scanning automatically on every single pull request, exactly as covered in Chapter 4, catching issues at the earliest, cheapest possible point — before code is even merged.

The Prioritize-by-Severity Pattern treats scanning results as a triaged backlog rather than an all-or-nothing gate, tackling the most severe, highest-confidence findings first, especially valuable when adopting scanning on a large, pre-existing codebase with an initial backlog of alerts.

The Documented-Dismissal Pattern requires every dismissed alert to include a clear, written reason, creating an auditable trail that future reviewers — including the original developer’s future self — can understand and, if needed, revisit.

Common anti-patterns to avoid: the Alert Fatigue Spiral (enabling an overly broad query suite without the team capacity to review the resulting volume, leading to alerts being ignored wholesale); the Silent Dismissal (dismissing alerts without any documented reasoning, leaving no trail for later review); and the Scan-Only-Sometimes Pattern (running code scanning manually and occasionally rather than automatically on every pull request, reintroducing the exact gap in consistent coverage the tool exists to close).

Common mistakes beginners make: assuming code scanning replaces the need for human code review, rather than complementing it; dismissing alerts based on a quick assumption instead of genuinely tracing the flagged path; and enabling the broadest possible query suite immediately, generating more alerts than the team has capacity to meaningfully review.