Add git version check for overlay analysis enablement #3370

Copilot · 2025-12-16T16:09:09Z

Overlay analysis depends on getFileOidsUnderPath, which uses git ls-files --format option introduced in Git 2.38.0. This adds a version check to ensure overlay analysis is only enabled when the git version is new enough.

Changes

src/git-utils.ts:
- Added GIT_MINIMUM_VERSION_FOR_OVERLAY constant ("2.38.0")
- Added getGitVersionOrThrow() function that throws with detailed error messages
- Added getGitVersion() function with caching and error logging
- Added gitVersionAtLeast() function for semver comparison
- Added logGitVersionTelemetry() function to log git version as telemetry diagnostic
- Added resetCachedGitVersion() for testing support
src/config-utils.ts: Added git version check in getOverlayDatabaseMode() that falls back to non-overlay analysis with a warning if git is too old
src/diagnostics.ts: Added makeTelemetryDiagnostic() helper function for creating telemetry-only diagnostics
src/init-action.ts:
- Added call to logGitVersionTelemetry() for git version telemetry
- Refactored bundle-download-telemetry and zstd-availability diagnostics to use makeTelemetryDiagnostic()
Tests: Added tests for version parsing (including Windows-style versions like 2.40.0.windows.1), caching behavior, and overlay fallback scenarios

When git version is insufficient, users will see:

Cannot build an overlay database because the installed Git version is older than 2.38.0. Falling back to creating a normal full database instead.

Risk assessment

Low risk: Changes add a precondition check to existing overlay analysis feature. Falls back gracefully to full database creation.

Which use cases does this change impact?

Workflow types:

Advanced setup - Impacts users who have custom CodeQL workflows.
Managed - Impacts users with dynamic workflows (Default Setup, CCR, ...).

Products:

Code Scanning - The changes impact analyses when analysis-kinds: code-scanning.

Environments:

Dotcom - Impacts CodeQL workflows on github.com and/or GitHub Enterprise Cloud with Data Residency.
GHES - Impacts CodeQL workflows on GitHub Enterprise Server.

How did/will you validate this change?

Unit tests - I am depending on unit test coverage (i.e. tests in .test.ts files).

If something goes wrong after this change is released, what are the mitigation and rollback strategies?

Rollback - Change can only be disabled by rolling back the release or releasing a new version with a fix.

How will you know if something goes wrong after this change is released?

Telemetry - I rely on existing telemetry or have made changes to the telemetry.
- Dashboards - I will watch relevant dashboards for issues after the release.

Are there any special considerations for merging or releasing this change?

No special considerations - This change can be merged at any time.

Merge / deployment checklist

Confirm this change is backwards compatible with existing workflows.
Consider adding a changelog entry for this change.
Confirm the readme and docs have been updated if necessary.

Original prompt

Overlay analysis depends on getFileOidsUnderPath, which requires a git version of at least 2.38.0. Update the enablement check for overlay to ensure the git version is new enough

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Overlay analysis depends on `getFileOidsUnderPath`, which uses `git ls-files --format` option that requires Git 2.38.0+. This change adds a check for the git version before enabling overlay analysis. Co-authored-by: henrymercer <14129055+henrymercer@users.noreply.github.com>

- Add test for Windows-style git version format - Add comment clarifying regex extracts major.minor.patch - Replace dynamic import with static import for semver Co-authored-by: henrymercer <14129055+henrymercer@users.noreply.github.com>

Copilot

Pull request overview

This PR adds Git version checking to ensure overlay analysis is only enabled when Git 2.38.0 or newer is available. Overlay analysis depends on the git ls-files --format option introduced in Git 2.38.0, and this change prevents runtime failures when an older Git version is installed.

Key changes:

Added Git version detection and comparison utilities
Integrated version check into overlay analysis enablement logic
Falls back to full database analysis with a warning when Git is too old

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/git-utils.ts	Added version constants, parsing function, and comparison utilities for Git version checking
src/git-utils.test.ts	Added comprehensive test coverage for version parsing and comparison logic
src/config-utils.ts	Integrated Git version check into overlay database mode determination
src/config-utils.test.ts	Added test cases for overlay fallback scenarios with old/missing Git versions
lib/*.js	Generated JavaScript output from TypeScript compilation

henrymercer · 2025-12-16T17:09:37Z

@copilot Please address the following feedback:

Error handling improvements

Cache the version of git, so we don't need to recompute it if we call gitVersionAtLeast multiple times
Refactor getGitVersion to getGitVersionOrThrow, and log the error message in gitVersionAtLeast, so we can debug using the original error message.

Telemetry

Add a helper function to diagnostics.ts that creates a telemetry diagnostic like the one we're creating for codeql-action/bundle-download-telemetry.
Modify getGitVersion to log a telemetry diagnostic with the git version number.

…metry - Cache the git version to avoid recomputing on repeated calls - Refactor getGitVersion to getGitVersionOrThrow with detailed errors - Add getGitVersion that logs errors and handles caching - Add makeTelemetryDiagnostic helper to diagnostics.ts - Add logGitVersionTelemetry function to log git version telemetry - Call logGitVersionTelemetry in init-action.ts - Add resetCachedGitVersion for testing - Update tests to work with new function signatures and caching Co-authored-by: henrymercer <14129055+henrymercer@users.noreply.github.com>

Refactored bundle-download-telemetry and zstd-availability diagnostics in init-action.ts to use the new makeTelemetryDiagnostic helper function. Also added guard for empty languages array in logGitVersionTelemetry. Co-authored-by: henrymercer <14129055+henrymercer@users.noreply.github.com>

Copilot · 2025-12-16T17:25:18Z

@copilot Please address the following feedback:

Error handling improvements

...

Addressed in commits c3dc529 and 393c074:

Error handling improvements:

Added caching for git version via cachedGitVersion module variable
Refactored to getGitVersionOrThrow() that throws with detailed error messages
getGitVersion() now logs errors with original message via getErrorMessage(e)
Added resetCachedGitVersion() for testing

Telemetry:

Added makeTelemetryDiagnostic() helper in diagnostics.ts
Added logGitVersionTelemetry() function that logs git version to telemetry
Called from init-action.ts after bundle download telemetry
Refactored existing bundle-download-telemetry and zstd-availability diagnostics to use the new helper

mbg

I have given this an initial review. Two primary points:

I am not keen on having the logging/diagnostic code in git-utils. That should essentially just have getGitVersionOrThrow in it along with maybe the caching.
The quality of the tests is somewhat poor.

mbg · 2025-12-17T09:21:02Z

src/git-utils.ts

+import type { Config } from "./config-utils";
+import { addDiagnostic, makeTelemetryDiagnostic } from "./diagnostics";
+import { Logger } from "./logging";


I am not overly keen on having this in git-utils. I think it would make more sense to keep this file for the git-related utility functions and then perform the version check / logging / diagnostic stuff elsewhere.

I've moved the logging/diagnostics elsewhere, so now it's just the ability to get the git version. I think that's not worth moving to a new file.

src/git-utils.ts

mbg · 2025-12-17T09:23:32Z

src/diagnostics.ts

+ * displayed on the status page or CLI summary table.
+ *
+ * @param id An identifier under which it makes sense to group this diagnostic message.
+ * @param name Display name for the ID.


Suggested change

* @param name Display name for the ID.

* @param name Display name for the diagnostic.

mbg · 2025-12-17T09:30:28Z

src/config-utils.test.ts

  languages: [KnownLanguage.javascript],
  codeqlVersion: CODEQL_OVERLAY_MINIMUM_VERSION,
  gitRoot: "/some/git/root",
+  gitVersion: "2.40.0", // Default to a version that supports overlay analysis


Why is this not GIT_MINIMUM_VERSION_FOR_OVERLAY by default? Having a different version here might mislead someone into thinking that 2.40.0 is the minimum required, and it means we don't test the case for where the git version is exactly 2.38.0.

mbg · 2025-12-17T09:31:39Z

src/git-utils.test.ts

+    const version = await gitUtils.getGitVersionOrThrow();
+    t.is(version, "2.40.0");
+  } finally {
+    runGitCommandStub.restore();


This is not necessary.

mbg · 2025-12-17T09:47:51Z

src/git-utils.test.ts

+    runGitCommandStub.restore();
+    gitUtils.resetCachedGitVersion();


mbg · 2025-12-17T09:47:57Z

src/git-utils.test.ts

+  const messages: LoggedMessage[] = [];
+  const logger = getRecordingLogger(messages);


mbg · 2025-12-17T09:48:17Z

src/git-utils.test.ts

+    t.true(
+      messages.some(
+        (m) =>
+          m.type === "debug" &&
+          typeof m.message === "string" &&
+          m.message.includes("Could not determine Git version"),
+      ),
+    );


mbg · 2025-12-17T09:48:28Z

src/git-utils.test.ts

+    runGitCommandStub.restore();
+    gitUtils.resetCachedGitVersion();


mbg · 2025-12-17T09:54:46Z

src/git-utils.ts

+export const GIT_MINIMUM_VERSION_FOR_OVERLAY = "2.38.0";
+
+/** Cached git version to avoid recomputing it multiple times. */
+let cachedGitVersion: string | undefined;


Observation: This will cache the git version for one step in a workflow (e.g. init), but not across steps (e.g. init and analyze).

I think that's probably OK based on the current usage where logGitVersionTelemetry is only called once in init, but does lead to two points:

What is the point of caching this if we only use it once right now?

If we start needing this elsewhere, then we still might not make use of the caching if the other uses are in steps other than init.

So this only becomes useful if we need the git version multiple times in the same action.

The caching makes for an easier API since we don't need to pass the git version around the program, but as you mention, we're not really making use of it now. I've removed it.

mbg

Thanks! Most of my feedback is addressed now, I think. I responded to the question in one of the conversations and added one new question. Other than those, this looks good now.

src/git-utils.ts

mbg · 2025-12-17T13:41:40Z

src/git-utils.ts

+  // Git version output can vary: "git version 2.40.0" or "git version 2.40.0.windows.1"
+  // We capture just the major.minor.patch portion to ensure semver compatibility.
+  const match = stdout.match(/git version (\d+\.\d+\.\d+)/);


It's probably OK for now, especially if we report the git version in telemetry. We can keep an eye out for unusual version formats that we might care about.

One possible improvement might be to document in the JSDoc that only the first three components are considered or, indeed, return a more structured type than string which also makes it clear that the version might be truncated to just those parts.

mbg · 2025-12-17T16:42:55Z

src/config-utils.ts

+    logger.info(`Using Git version ${gitVersion}`);
+    await logGitVersionTelemetry(config, gitVersion);
+  } catch (e) {
+    logger.debug(`Could not determine Git version: ${getErrorMessage(e)}`);


Question about the log-levels here. The actual failure here is logged at debug level, and so wouldn't ordinarily be visible (especially in dynamic workflows).

Meanwhile, the subsequent message in getOverlayDatabaseMode is logged at warning level and so would show up quite prominently in the log (including workflow annotations).

That could lead to a situation where the actual problem is not easily debuggable. Should this be a warning instead / in addition to the gitVersion === undefined message?

Initial plan

aff7998

Copilot AI assigned Copilot and henrymercer Dec 16, 2025

Copilot started work on behalf of henrymercer December 16, 2025 16:09 View session

Copilot AI and others added 2 commits December 16, 2025 16:22

Address code review feedback

fc2bbb0

- Add test for Windows-style git version format - Add comment clarifying regex extracts major.minor.patch - Replace dynamic import with static import for semver Co-authored-by: henrymercer <14129055+henrymercer@users.noreply.github.com>

github-actions bot added the size/M Should be of average difficulty to review label Dec 16, 2025

Copilot AI changed the title ~~[WIP] Update enablement check for overlay with git version requirement~~ Add git version check for overlay analysis enablement Dec 16, 2025

Copilot AI requested a review from henrymercer December 16, 2025 16:32

Copilot finished work on behalf of henrymercer December 16, 2025 16:32

henrymercer marked this pull request as ready for review December 16, 2025 16:56

henrymercer requested a review from a team as a code owner December 16, 2025 16:56

Copilot AI review requested due to automatic review settings December 16, 2025 16:56

henrymercer unassigned henrymercer and Copilot Dec 16, 2025

Copilot AI reviewed Dec 16, 2025

View reviewed changes

henrymercer removed their request for review December 16, 2025 16:56

Copilot started work on behalf of henrymercer December 16, 2025 17:10 View session

Copilot AI and others added 2 commits December 16, 2025 17:19

Copilot AI requested a review from henrymercer December 16, 2025 17:27

Copilot finished work on behalf of henrymercer December 16, 2025 17:27

henrymercer removed their request for review December 16, 2025 17:30

github-actions bot added size/L May be hard to review and removed size/M Should be of average difficulty to review labels Dec 16, 2025

mbg reviewed Dec 17, 2025

View reviewed changes

henrymercer added 2 commits December 17, 2025 11:49

Merge branch 'main' into copilot/update-overlay-git-version-check

32795b3

Remove caching mechanism

e052dbd

henrymercer added 3 commits December 17, 2025 12:06

Move git version logging to config utils

3765106

Remove unnecessary stub restores

9c5588d

Update makeTelemetryDiagnostic doc

056581e

github-actions bot added size/M Should be of average difficulty to review and removed size/L May be hard to review labels Dec 17, 2025

henrymercer requested a review from mbg December 17, 2025 15:21

mbg reviewed Dec 17, 2025

View reviewed changes

henrymercer added 2 commits December 17, 2025 17:27

Record both truncated and full git versions

a13b404

Bump log level for failing to parse git version

a2c3c8e

	* @param name Display name for the ID.
	* @param name Display name for the diagnostic.

		runGitCommandStub.restore();
		gitUtils.resetCachedGitVersion();

		const messages: LoggedMessage[] = [];
		const logger = getRecordingLogger(messages);

Add git version check for overlay analysis enablement #3370

Are you sure you want to change the base?

Add git version check for overlay analysis enablement #3370

Uh oh!

Conversation

Copilot AI commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Risk assessment

Which use cases does this change impact?

How did/will you validate this change?

If something goes wrong after this change is released, what are the mitigation and rollback strategies?

How will you know if something goes wrong after this change is released?

Are there any special considerations for merging or releasing this change?

Merge / deployment checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

henrymercer commented Dec 16, 2025

Error handling improvements

Telemetry

Uh oh!

Copilot AI commented Dec 16, 2025

Error handling improvements

Uh oh!

mbg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mbg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Dec 16, 2025 •

edited

Loading