Summary

downloadOverlayBaseDatabaseFromCache restores the overlay-base database by passing the key prefix as the primary key, with no restoreKeys:

actionsCache.restoreCache(
  [dbLocation],
  cacheRestoreKeyPrefix,
  undefined,
  { segmentTimeoutInMs: 3000 },
)

This depends on the primary key matching by prefix. GitHub's cache service does that, but some Actions-cache-compatible backends only prefix-match restoreKeys. One example is the transparent cache on Blacksmith runners. On those backends, PR runs can never restore the overlay-base database, even though default-branch runs upload it successfully. Every PR run then falls back to a full analysis.

What we see

Default-branch run, on the same runner type:

Setting overlay database mode to overlay-base with caching because we are analyzing the default branch.
Uploading overlay-base database to Actions cache with key codeql-overlay-base-database-1-<hash>-python-2.27.1-<sha>-<run_id>-1
Successfully uploaded overlay-base database from /home/runner/_work/_temp/codeql_databases

Pull request run:

Setting overlay database mode to overlay with caching because we are analyzing a pull request.
Looking in Actions cache for overlay-base database with restore key codeql-overlay-base-database-1-<hash>-python-2.27.1-
No overlay-base database found in Actions cache
No overlay-base database found in cache, reverting overlay database mode to none.

Minimal reproduction of the backend difference

A cache entry saved as probe-<run_id>-full, then restored in a later job on the same branch with actions/cache/restore@v4:

Suggested fix

Also pass the prefix as a restore key:

actionsCache.restoreCache(
  [dbLocation],
  cacheRestoreKeyPrefix,
  [cacheRestoreKeyPrefix],
  { segmentTimeoutInMs: 3000 },
)

On GitHub's cache this matches exactly the same entries as today, since the prefix is tried first either way. On backends that only prefix-match restore keys, overlay analysis starts working.

Environment

• github/codeql-action/init and analyze @v4, CodeQL bundle 2.27.1
• build-mode: none, languages python and javascript-typescript
• Third-party hosted runners (Blacksmith) whose actions/cache calls go to their own cache backend