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

Add an unused getCodeQlVersionsForOverlayBaseDatabases(rawLanguages: string[], logger: Logger) function that looks up overlay base databases for the provided languages 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

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

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

The cache keys only contain parsed languages. I've updated the methods so the existing code paths do not resolve any aliases.

This seems to have completely disappeared from the code now (for both stores and restores). Is that intentional?

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

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

We want to match the CLI version used in the base database as closely as possible. Since we're only dealing with stable releases, our goal is to just to download the same CodeQL version as the base DB. (Though we provide the full list so if the feature flags explicitly disable a particular CodeQL version due to a bug, we can ignore that version.)

Sorry, I think you misunderstood my comment. I obviously understand what the goal of this work is, but I didn't see how the implementation accomplished it.

Reviewing it again now, I see that the key detail is that the call to listActionsCaches(cacheKeyPrefix) is given the cacheKeyPrefix which already includes the target CodeQL CLI version. I seem to have missed that previously, and so didn't see how the caches were filtered to the right CLI version. It looked to me as if we just retrieved a list of all overlay caches.

It might be good to document this (critical) detail in the code and link to https://docs.github.com/en/rest/actions/cache?apiVersion=2026-03-10#list-github-actions-caches-for-a-repository which documents that the key parameter can be a prefix.

mbg

(Requesting changes to prevent accidental merges.)

I have re-reviewed, thanks for making changes and responding to the previous comments. There is one larger design point I want to flag, and otherwise just a couple of smaller points that follow-up on previous comments.

mbg · 2026-04-30T09:51:13Z

+/**
+ * Lists overlay-base database cache entries with the given key prefix, ignoring entries that are
+ * old enough that they may be evicted by the Actions cache before we attempt to download them.
+ */
+async function listRecentOverlayBaseDatabaseCaches(
+  cacheKeyPrefix: string,
+  logger: Logger,
+): Promise<ActionsCacheItem[]> {


Sorry to be very critical here, but I don't think this is architecturally a good mitigation for the problem, and adds extra complexity for (IMHO) little gain.

Cache eviction is based on several criteria, and age is only one of them. This mitigation guards against the case where:

We are analysing a low-traffic repo

Around 7 days after the cache was last accessed

That's a valid problem and will happen once in a while, but isn't very common.

I am probably more concerned about high-traffic repos where workflows are uploading caches all the time, and may cause a cache we have identified to be evicted at essentially any time for space reasons. Checking the age of the cache we want doesn't guard against that. (Unless we also check all other caches to see how likely it is that ours would be evicted first, but I don't think that's worth the effort.)

I think realistically, a better solution might just be to stick this logic in a retry loop: find a suitable cache, try to download it, and if it fails attempt the process another time or two.

mbg · 2026-04-30T09:53:25Z

 import * as actionsUtil from "../actions-util";
 import * as apiClient from "../api-client";
-import { ResolveDatabaseOutput } from "../codeql";
+import { type ResolveDatabaseOutput } from "../codeql";


Minor (type in the { } only disambiguates, while in front doesn't require the module at runtime iirc? Not overly relevant here since it's a test file, but a general point):

Suggested change

import { type ResolveDatabaseOutput } from "../codeql";

import type { ResolveDatabaseOutput } from "../codeql";

mbg · 2026-04-30T10:06:40Z

+/**
+ * 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(


Sorry, I think you misunderstood my comment. I obviously understand what the goal of this work is, but I didn't see how the implementation accomplished it.

Reviewing it again now, I see that the key detail is that the call to listActionsCaches(cacheKeyPrefix) is given the cacheKeyPrefix which already includes the target CodeQL CLI version. I seem to have missed that previously, and so didn't see how the caches were filtered to the right CLI version. It looked to me as if we just retrieved a list of all overlay caches.

It might be good to document this (critical) detail in the code and link to https://docs.github.com/en/rest/actions/cache?apiVersion=2026-03-10#list-github-actions-caches-for-a-repository which documents that the key parameter can be a prefix.

mbg · 2026-04-30T10:11:49Z

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


This seems to have completely disappeared from the code now (for both stores and restores). Is that intentional?

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

Comment thread src/status-report.ts

mbg requested changes Apr 13, 2026

View reviewed changes

henrymercer mentioned this pull request Apr 13, 2026

Refactoring: Introduce overlay/caching.ts #3819

Merged

henrymercer added 4 commits April 21, 2026 22:18

Retrieve CodeQL versions associated with cached overlay base DBs

201ddc2

Document exclusion of nightlies

5026833

Use type-only imports

af1f613

Mitigate caches being evicted before they can be downloaded

1279e8d

henrymercer force-pushed the henrymercer/determine-overlay-version branch from 0d23c4e to 1279e8d Compare April 21, 2026 23:05

github-actions Bot added size/M Should be of average difficulty to review and removed size/XXL May be extremely hard to review labels Apr 21, 2026

henrymercer requested a review from mbg April 21, 2026 23:15

oscarsj approved these changes Apr 30, 2026

View reviewed changes

mbg requested changes Apr 30, 2026

View reviewed changes

	import { type ResolveDatabaseOutput } from "../codeql";
	import type { ResolveDatabaseOutput } from "../codeql";

Conversation

henrymercer commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

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!

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!

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!

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!

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!

4 participants

henrymercer commented Apr 10, 2026 •

edited

Loading

mbg left a comment •

edited

Loading