Skip to content

Add incremental analysis documentation for the CodeQL CLI#44272

Closed
coadaflorin wants to merge 1 commit into
github:mainfrom
coadaflorin:add-incremental-analysis-docs
Closed

Add incremental analysis documentation for the CodeQL CLI#44272
coadaflorin wants to merge 1 commit into
github:mainfrom
coadaflorin:add-incremental-analysis-docs

Conversation

@coadaflorin
Copy link
Copy Markdown
Contributor

Summary

This PR adds a new article to the "Scan from the command line" section covering incremental analysis with the CodeQL CLI. The article documents two complementary features for speeding up CodeQL analysis on pull requests:

  • Diff-informed analysis — restricts query results to alerts within the PR diff, making analysis faster and more focused.
  • Overlay analysis — builds on a cached base database from the default branch instead of creating a full database from scratch, dramatically reducing database creation and query evaluation time.

Changes

  • New file: content/code-security/.../scan-from-the-command-line/incremental-analysis.md — comprehensive how-to guide covering both features with step-by-step instructions, CLI flags, requirements, and a decision matrix.
  • Updated: index.md — added the new article to the children list.

Source

Content adapted from the internal CI integrator guide at github/semmle-code (documentation/markdown-internal/incremental-codeql-ci.md), rewritten to match the GitHub Docs style and conventions.

Article structure

  1. About incremental analysis — overview of both features
  2. Diff-informed analysis — concept, step-by-step guide (determine diff → parse ranges → create extension pack → run queries → filter SARIF), CLI flags summary
  3. Overlay analysis — concept, requirements, overlay-base mode (default branch), overlay mode (PRs), CLI flags summary, minimum CLI versions
  4. Using both features together — decision matrix for different scenarios

Add a new article covering diff-informed analysis and overlay analysis,
two complementary features that speed up CodeQL analysis for pull requests
when using the CodeQL CLI in CI systems.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings May 14, 2026 10:55
@github-actions github-actions Bot added the triage Do not begin working on this issue until triaged by the team label May 14, 2026
@github-actions
Copy link
Copy Markdown
Contributor

How to review these changes 👓

Thank you for your contribution. To review these changes, choose one of the following options:

A Hubber will need to deploy your changes internally to review.

Table of review links

Note: Please update the URL for your staging server or codespace.

The table shows the files in the content directory that were changed in this pull request. This helps you review your changes on a staging server. Changes to the data directory are not included in this table.

Source Review Production What Changed
New file: code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/incremental-analysis.md fpt
ghec
ghes@ 3.21 3.20 3.19 3.18 3.17 3.16
fpt
ghec
ghes@ 3.21 3.20 3.19 3.18 3.17 3.16
code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/index.md fpt
ghec
ghes@ 3.21 3.20 3.19 3.18 3.17 3.16
fpt
ghec
ghes@ 3.21 3.20 3.19 3.18 3.17 3.16

Key: fpt: Free, Pro, Team; ghec: GitHub Enterprise Cloud; ghes: GitHub Enterprise Server

🤖 This comment is automatically generated.

@coadaflorin coadaflorin deleted the add-incremental-analysis-docs branch May 14, 2026 11:00
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new “Incremental analysis” how-to under the CodeQL CLI “Scan from the command line” section, documenting diff-informed analysis and overlay analysis to speed up pull request scanning workflows.

Changes:

  • Added a new article describing diff-informed analysis (diff range extension pack + SARIF filtering) and overlay analysis (overlay-base + overlay mode).
  • Updated the section index to include the new incremental analysis article.
Show a summary per file
File Description
content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/index.md Adds the new incremental analysis page to the navigation children list.
content/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/incremental-analysis.md New documentation page covering incremental analysis techniques (diff-informed and overlay) with steps, flags, and guidance.

Copilot's findings

  • Files reviewed: 2/2 changed files
  • Comments generated: 1

Comment on lines +64 to +67
1. For lines starting with `@@`, parse the hunk header `@@ -X,Y +Z,W @@` to find `Z` (the starting line number in the new file). Set `currentLine = Z`.
1. For lines starting with `+` (additions), record the start of a new range if one isn't in progress. Increment `currentLine`.
1. For lines starting with `-` (deletions), skip the line. Deletions don't affect new-file line numbers.
1. For context lines (starting with a space), close any in-progress range and increment `currentLine`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage Do not begin working on this issue until triaged by the team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants