Add git version check for overlay analysis enablement by Copilot · Pull Request #3370 · github/codeql-action · GitHub

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>

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

@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 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

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.

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.

Suggested change

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

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.

This is not necessary.

As above.

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.

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.

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.

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?

Thanks for adding this! This should make it more obvious what's going on.

One comment: we might want to think about whether it is worthwhile to store whatever we get from git --version after ^git version as the fullVersion and then only store truncatedVersion if it matches the \d+\.\d+\.\d+ pattern. As it stands, we only store the fullVersion if it starts with the semver-like pattern.

I don't think this is a big deal since I'd expect the git versions to always start with at least three numeric components, so this probably doesn't need to be addressed at this point unless we find that we are missing data for troubleshooting purposes.

I don't think this is a big deal since I'd expect the git versions to always start with at least three numeric components, so this probably doesn't need to be addressed at this point unless we find that we are missing data for troubleshooting purposes.

Agreed, I'll leave this as-is for now.

Suggested change

      
              // Should extract just the major.minor.patch portion
          
              // Should extract just the major.minor.patch portion as `truncatedVersion`

I am not sure what motivated this change, but it reminded me that we might want to check that this works correctly across platforms depending on what git uses for line endings in its output there. I think I tried to do something like that for my tests in #3318

LGTM, aside from one oversight(?)

You added TOLERATE_MISSING_GIT_VERSION to the EnvVar enum, but aren't using it here.

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 Bot 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 Bot 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 Bot and others added 2 commits December 16, 2025 17:19

Copilot Bot 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 5 commits December 17, 2025 17:27

Record both truncated and full git versions

a13b404

Bump log level for failing to parse git version

a2c3c8e

Avoid non-determinism in PR checks due to overlay FFs

003ddae

Throw in test mode if can't compute git version

358a55e

Trim git version output

cec3cc5

mbg reviewed Dec 18, 2025

View reviewed changes

henrymercer added 5 commits December 18, 2025 13:01

Test mode: Tolerate missing git binary

948c7fb

Improve comment

ff84c6f

Only enable overlay for the code scanning suite

a7e88a4

Prefer explicit env var to binary accessibility check

95246ce

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

034401b

mbg previously approved these changes Dec 18, 2025

View reviewed changes

Use EnvVar

8b428c0

henrymercer dismissed mbg’s stale review via 8b428c0 December 18, 2025 14:34

mbg previously approved these changes Dec 18, 2025

View reviewed changes

Fix import order

3b6fef6

henrymercer dismissed mbg’s stale review via 3b6fef6 December 18, 2025 14:40

mbg approved these changes Dec 18, 2025

View reviewed changes

henrymercer merged commit f67ec12 into main Dec 18, 2025

henrymercer deleted the copilot/update-overlay-git-version-check branch December 18, 2025 15:47

This was referenced Jan 12, 2026

Merge main into releases/v4 #3394

Merged

Merge releases/v4 into releases/v3 #3396

Merged

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

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

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

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

+              /**
+               * Git version information
+               *
+               * The full version string as reported by `git --version` may not be
+               * semver-compatible (e.g., "2.40.0.windows.1"). This class captures both
+               * the full version string and a truncated semver-compatible version string
+               * (e.g., "2.40.0").
+               */
+              export class GitVersionInfo {
+                constructor(
+                  /** Truncated semver-compatible version */
+                  public truncatedVersion: string,
+                  /** Full version string as reported by `git --version` */
+                  public fullVersion: string,
+                ) {}
+                isAtLeast(minVersion: string): boolean {
+                  return semver.gte(this.truncatedVersion, minVersion);
+                }
+              }

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

+               * 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.

	* @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);

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

+                // 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+)/);

+                const match = stdout.match(/^git version ((\d+\.\d+\.\d+).*)$/);
                 if (match?.[1]) {
-                  return match[1];
+                  return new GitVersionInfo(match[2], match[1]);

	// Should extract just the major.minor.patch portion
	// Should extract just the major.minor.patch portion as `truncatedVersion`

               test("getGitVersionOrThrow returns version for valid git output", async (t) => {
-                sinon.stub(gitUtils as any, "runGitCommand").resolves("git version 2.40.0\n");
+                sinon.stub(gitUtils as any, "runGitCommand").resolves("git version 2.40.0");

+                  // Docker container where git may not be available.
+                  if (
+                    isInTestMode() &&
+                    process.env.CODEQL_ACTION_TOLERATE_MISSING_GIT_VERSION !== "true"

Add git version check for overlay analysis enablement by Copilot · Pull Request #3370 · github/codeql-action · GitHub

Uh oh!

Add git version check for overlay analysis enablement - #3370

Add git version check for overlay analysis enablement#3370henrymercer merged 22 commits intomaingithub/codeql-action:mainfrom copilot/update-overlay-git-version-checkgithub/codeql-action:copilot/update-overlay-git-version-checkCopy head branch name to clipboard

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!

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!

Choose a reason for hiding this comment

Uh oh!

mbg left a comment

Choose a reason for hiding this comment

Uh oh!

Add git version check for overlay analysis enablement#3370
henrymercer merged 22 commits into
mainfrom
copilot/update-overlay-git-version-check

Copilot AI commented Dec 16, 2025 •
edited
Loading