Overlay: Determine which versions of CodeQL are compatible with cached base DBs by henrymercer · Pull Request #3809 · github/codeql-action

henrymercer · 2026-04-10T14:35:44Z

Refactor caching logic into overlay/caching.ts
Add an unused getCompatibleCodeQlVersionsForOverlayBaseDatabases(config, logger) function that looks up overlay base databases for the languages in config and returns a list of the CodeQL versions that were used to generate those overlay base databases. The intention is to use this in a future PR to determine what CodeQL version to set up. Returning a list rather than just the latest means we can filter the list down based on the enabled default version feature flags. This gives us the ability to skip a CodeQL version that we might initially roll out but then decide to rollback.

Risk assessment

For internal use only. Please select the risk level of this change:

Low risk: Changes are fully under feature flags, or have been fully tested and validated in pre-production environments and are highly observable, or are documentation or test only.

Which use cases does this change impact?

None yet.

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.
- Alerts - New or existing monitors will trip if something goes wrong with this change.

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.

Copilot

Pull request overview

Refactors overlay base-database caching into a dedicated module and introduces a helper to discover which CodeQL CLI versions are represented in existing cached overlay base databases (to support future version-selection logic).

Changes:

Moved overlay base DB cache download/upload and cache-key generation logic into src/overlay/caching.ts and added src/overlay/caching.test.ts.
Extracted OverlayDatabaseMode into src/overlay/overlay-database-mode.ts and updated imports across the codebase.
Added getCompatibleCodeQlVersionsForOverlayBaseDatabases(config, logger) to list CodeQL versions inferred from matching cache entries.

Show a summary per file

File	Description
src/testing-utils.ts	Updates `OverlayDatabaseMode` import path after enum extraction.
src/status-report.ts	Updates overlay cache stats type import to the new caching module.
src/overlay/overlay-database-mode.ts	New enum module for overlay database mode.
src/overlay/index.ts	Removes caching responsibilities; retains overlay file/OID helpers and version constants.
src/overlay/index.test.ts	Removes overlay caching tests that were moved to the new caching test file.
src/overlay/caching.ts	New home for overlay base DB cache logic + compatible-version discovery helper.
src/overlay/caching.test.ts	Adds unit tests for cache key stability, cache restore behavior, and compatible-version discovery.
src/init-action.ts	Switches overlay cache download imports to `overlay/caching` and enum to `overlay-database-mode`.
src/init-action-post-helper.ts	Updates `OverlayDatabaseMode` import path.
src/init-action-post-helper.test.ts	Updates `OverlayDatabaseMode` import path.
src/database-upload.ts	Updates `OverlayDatabaseMode` import path.
src/config-utils.ts	Updates `OverlayDatabaseMode` import path; keeps overlay min-version constants from `overlay/index`.
src/config-utils.test.ts	Updates `OverlayDatabaseMode` import path.
src/codeql.ts	Updates `OverlayDatabaseMode` import path.
src/analyze.ts	Updates `OverlayDatabaseMode` import path.
src/analyze-action.ts	Switches overlay cache upload import to `overlay/caching`.
lib/upload-sarif-action-post.js	Generated build output update.
lib/upload-lib.js	Generated build output update.
lib/start-proxy-action-post.js	Generated build output update.
lib/resolve-environment-action.js	Generated build output update.
lib/init-action.js	Generated build output update.
lib/init-action-post.js	Generated build output update.
lib/autobuild-action.js	Generated build output update.
lib/analyze-action.js	Generated build output update.
lib/analyze-action-post.js	Generated build output update.

Copilot's findings

Files reviewed: 16/28 changed files
Comments generated: 1

Copilot · 2026-04-10T14:44:15Z

src/status-report.ts

 import { getRef } from "./git-utils";
 import { Logger } from "./logging";
-import { OverlayBaseDatabaseDownloadStats } from "./overlay";
+import { OverlayBaseDatabaseDownloadStats } from "./overlay/caching";


OverlayBaseDatabaseDownloadStats is only used as a type in this file. Consider switching this to a type-only import to avoid pulling src/overlay/caching.ts (and its runtime deps like @actions/cache) into the status-report module at runtime.

Suggested change

import { OverlayBaseDatabaseDownloadStats } from "./overlay/caching";

import type { OverlayBaseDatabaseDownloadStats } from "./overlay/caching";

mbg

Thanks for working on this! This is much simpler than the previous attempt at addressing this problem.

I have picked "Request changes" here because there are a few comments that I had which we should think about before we merge this.

Also, it might be good to have a separate PR for the first commit. That would make it easier to verify that it's just a refactoring, which I think we can merge straight away. It would then reduce the noise here.

mbg · 2026-04-13T15:09:54Z

src/overlay/caching.ts

+    return knownLanguageAliases[
+      normalized as keyof typeof knownLanguageAliases
+    ];


Note that this is a breaking change in the sense that any previously uploaded caches which include language aliases in the cache key will no longer be restored once this ships.

mbg · 2026-04-13T15:13:09Z

src/overlay/caching.ts

+  // Parse CodeQL versions from cache keys.
+  // After the prefix, the remaining key format starts with
+  // `${codeQlVersion}-`.
+  const versionRegex = /^([\d.]+)-/;


What happens here if a cache was uploaded for a pre-release CLI?

Also should the . be escaped?

mbg · 2026-04-13T15:14:08Z

src/overlay/caching.ts

+  logger.info(
+    `Compatible CodeQL versions in overlay-base database caches: ${compatibleVersions.join(", ")}`,
+  );


Minor: This could be quite long. Also, isn't this just the list of CodeQL versions, not the compatible ones?

mbg · 2026-04-13T15:16:27Z

src/overlay/caching.ts

+/**
+ * Searches the GitHub Actions cache for overlay-base databases matching the
+ * languages in the given config, and returns all compatible CodeQL versions
+ * found across matching cache entries.
+ *
+ * @param config The configuration object containing the languages to match
+ * @param logger The logger instance
+ * @returns Unique compatible CodeQL versions found in cached overlay-base
+ * databases, sorted from latest to earliest.
+ */
+export async function getCompatibleCodeQlVersionsForOverlayBaseDatabases(


I am confused about the notion of "compatible" here, since this function just seems to extract all the CodeQL CLI versions from the cache keys. I don't see anything that would make a given CLI version compatible or not compatible.

mbg · 2026-04-13T15:21:10Z

src/overlay/caching.ts

+      `prefix ${cacheKeyPrefix}`,
+  );
+
+  const caches = await listActionsCaches(cacheKeyPrefix);


Note that the approach of listing available caches, performing some checks, and then fetching a particular cache later opens us up to race conditions where a cache may be available when we list them, but no longer when we try to download it.

That's probably not going to happen often and is generally not very likely, but we should consider it.

henrymercer added 2 commits April 10, 2026 14:55

Refactoring: Introduce overlay/caching.ts

4e8c9ce

Determine compatible CodeQL versions for cached base DBs

0d23c4e

henrymercer requested a review from a team as a code owner April 10, 2026 14:35

Copilot AI review requested due to automatic review settings April 10, 2026 14:35

github-actions bot added the size/XXL May be extremely hard to review label Apr 10, 2026

Copilot started reviewing on behalf of henrymercer April 10, 2026 14:36 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

mbg requested changes Apr 13, 2026

View reviewed changes

henrymercer mentioned this pull request Apr 13, 2026

Refactoring: Introduce overlay/caching.ts #3819

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overlay: Determine which versions of CodeQL are compatible with cached base DBs#3809

Overlay: Determine which versions of CodeQL are compatible with cached base DBs#3809
henrymercer wants to merge 2 commits intomainfrom
henrymercer/determine-overlay-version

henrymercer commented Apr 10, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

mbg left a comment •

edited

Loading

Uh oh!

mbg Apr 13, 2026

Uh oh!

mbg Apr 13, 2026

Uh oh!

mbg Apr 13, 2026

Uh oh!

mbg Apr 13, 2026

Uh oh!

mbg Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	import { OverlayBaseDatabaseDownloadStats } from "./overlay/caching";
	import type { OverlayBaseDatabaseDownloadStats } from "./overlay/caching";

Conversation

henrymercer commented Apr 10, 2026

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

Copilot's findings

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

mbg left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mbg Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

mbg Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

mbg Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

mbg Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

mbg Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mbg left a comment •

edited

Loading