Skip to content

Graduate overlay TRAP caching defaults #4245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
henrymercer wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Graduate overlay TRAP caching defaults #4245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e038b67
Graduate overlay TRAP caching defaults
henrymercer Oct 15, 2026
e344c79
Document TRAP caching default with improved incremental analysis
henrymercer Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion init/action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,10 @@ inputs:
required: false
trap-caching:
description: >-
Explicitly enable or disable TRAP caching rather than respecting the feature flag for it.
Explicitly enable or disable TRAP caching instead of using the automatically determined default.
TRAP caching is disabled by default when improved incremental analysis is enabled,
because improved incremental analysis of a pull request only extracts changed files,
which rarely benefit from TRAP caching.
required: false
dependency-caching:
description: >-
Expand Down
11 changes: 3 additions & 8 deletions lib/entry-points.js
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

76 changes: 27 additions & 49 deletions src/config-utils.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2126,85 +2126,68 @@ test.serial("getPrimaryAnalysisConfig - Code Scanning + Code Quality", (t) => {
});

test.serial(
"isTrapCachingEnabled: explicit input true is respected",
"isTrapCachingEnabled: explicit true input overrides self-hosted default",
async (t) => {
return await withTmpDir(async (tmpDir) => {
setupActionsVars(tmpDir, tmpDir);
sinon
.stub(actionsUtil, "getOptionalInput")
.withArgs("trap-caching")
.returns("true");
t.true(
await configUtils.isTrapCachingEnabled(
createFeatures([]),
OverlayDatabaseMode.None,
),
);
t.true(configUtils.isTrapCachingEnabled(OverlayDatabaseMode.None));
});
},
);

test.serial(
"isTrapCachingEnabled: disabled on self-hosted runner by default",
"isTrapCachingEnabled: explicit true input overrides overlay defaults",
async (t) => {
return await withTmpDir(async (tmpDir) => {
setupActionsVars(tmpDir, tmpDir);
setupActionsVars(tmpDir, path.join(tmpDir, "hostedtoolcache"));
sinon
.stub(actionsUtil, "getOptionalInput")
.withArgs("trap-caching")
.returns(undefined);
t.false(
await configUtils.isTrapCachingEnabled(
createFeatures([]),
OverlayDatabaseMode.None,
),
);
.returns("true");
for (const overlayDatabaseMode of [
OverlayDatabaseMode.Overlay,
OverlayDatabaseMode.OverlayBase,
]) {
t.true(configUtils.isTrapCachingEnabled(overlayDatabaseMode));
}
});
},
);

test.serial(
"isTrapCachingEnabled: enabled on hosted runner by default",
"isTrapCachingEnabled: explicit false input overrides hosted default",
async (t) => {
return await withTmpDir(async (tmpDir) => {
const hostedToolCache = path.join(tmpDir, "hostedtoolcache");
setupActionsVars(tmpDir, hostedToolCache);
setupActionsVars(tmpDir, path.join(tmpDir, "hostedtoolcache"));
sinon
.stub(actionsUtil, "getOptionalInput")
.withArgs("trap-caching")
.returns(undefined);
t.true(
await configUtils.isTrapCachingEnabled(
createFeatures([]),
OverlayDatabaseMode.None,
),
);
.returns("false");
t.false(configUtils.isTrapCachingEnabled(OverlayDatabaseMode.None));
});
},
);

test.serial(
"isTrapCachingEnabled: enabled on hosted runner when overlay enabled but feature flag off",
"isTrapCachingEnabled: disabled on self-hosted runner by default",
async (t) => {
return await withTmpDir(async (tmpDir) => {
const hostedToolCache = path.join(tmpDir, "hostedtoolcache");
setupActionsVars(tmpDir, hostedToolCache);
setupActionsVars(tmpDir, tmpDir);
sinon
.stub(actionsUtil, "getOptionalInput")
.withArgs("trap-caching")
.returns(undefined);
t.true(
await configUtils.isTrapCachingEnabled(
createFeatures([]),
OverlayDatabaseMode.Overlay,
),
);
t.false(configUtils.isTrapCachingEnabled(OverlayDatabaseMode.None));
});
},
);

test.serial(
"isTrapCachingEnabled: disabled on hosted runner when overlay enabled and feature flag on",
"isTrapCachingEnabled: enabled on hosted runner without overlay analysis",
async (t) => {
return await withTmpDir(async (tmpDir) => {
const hostedToolCache = path.join(tmpDir, "hostedtoolcache");
Expand All @@ -2213,18 +2196,13 @@ test.serial(
.stub(actionsUtil, "getOptionalInput")
.withArgs("trap-caching")
.returns(undefined);
t.false(
await configUtils.isTrapCachingEnabled(
createFeatures([Feature.OverlayAnalysisDisableTrapCaching]),
OverlayDatabaseMode.Overlay,
),
);
t.true(configUtils.isTrapCachingEnabled(OverlayDatabaseMode.None));
});
},
);

test.serial(
"isTrapCachingEnabled: enabled on hosted runner when overlay is None even with feature flag on",
"isTrapCachingEnabled: disabled on hosted runner with overlay analysis",
async (t) => {
return await withTmpDir(async (tmpDir) => {
const hostedToolCache = path.join(tmpDir, "hostedtoolcache");
Expand All @@ -2233,12 +2211,12 @@ test.serial(
.stub(actionsUtil, "getOptionalInput")
.withArgs("trap-caching")
.returns(undefined);
t.true(
await configUtils.isTrapCachingEnabled(
createFeatures([Feature.OverlayAnalysisDisableTrapCaching]),
OverlayDatabaseMode.None,
),
);
for (const overlayDatabaseMode of [
OverlayDatabaseMode.Overlay,
OverlayDatabaseMode.OverlayBase,
]) {
t.false(configUtils.isTrapCachingEnabled(overlayDatabaseMode));
}
});
},
);
Expand Down
20 changes: 10 additions & 10 deletions src/config-utils.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -944,23 +944,23 @@ async function validateOverlayDatabaseMode(
});
}

export async function isTrapCachingEnabled(
features: FeatureEnablement,
/**
* Determines whether TRAP caching is enabled for the current run.
*
* @returns Whether TRAP caches should be downloaded and uploaded.
*/
export function isTrapCachingEnabled(
overlayDatabaseMode: OverlayDatabaseMode,
): Promise<boolean> {
): boolean {
// If the workflow specified something, always respect that.
const trapCaching = getOptionalInput("trap-caching");
if (trapCaching !== undefined) return trapCaching === "true";
Comment on lines 955 to 957

@mbg mbg Oct 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OOC: What happens if TRAP caching is explicitly enabled via the input, we restore the TRAP caches, but overlay analysis is also enabled? Would it be worth to document that here or in init/action.yml if that combination has effects on overlay analysis?

@henrymercer henrymercer Oct 16, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With overlay analysis enabled, the extractor only writes TRAP files for changed files, so the TRAP cache is only really ever useful for files with identical content that have just been moved. This means that the overhead of downloading the cache (and the space it takes up in the Actions cache) is rarely worth it.

It's a good idea to document that in the input, I'll push a commit to do that.


// On self-hosted runners which may have slow network access, disable TRAP caching by default.
if (!looksLikeHostedRunner()) return false;

// If overlay analysis is enabled, then disable TRAP caching since overlay analysis supersedes it.
// This change is gated behind a feature flag.
if (
overlayDatabaseMode !== OverlayDatabaseMode.None &&
(await features.getValue(Feature.OverlayAnalysisDisableTrapCaching))
) {
// Overlay analysis supersedes TRAP caching, so disable TRAP caching by default when it is active.
if (overlayDatabaseMode !== OverlayDatabaseMode.None) {
return false;
}

Expand Down Expand Up @@ -1302,7 +1302,7 @@ export async function initConfig(
logger,
);

if (await isTrapCachingEnabled(features, config.overlayDatabaseMode)) {
if (isTrapCachingEnabled(config.overlayDatabaseMode)) {
const { trapCaches, trapCacheDownloadTime } = await downloadCacheWithTime(
inputs.codeql,
config.languages,
Expand Down
7 changes: 0 additions & 7 deletions src/feature-flags.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,6 @@ export enum Feature {
OverlayAnalysisCodeScanningRuby = "overlay_analysis_code_scanning_ruby",
OverlayAnalysisCpp = "overlay_analysis_cpp",
OverlayAnalysisCsharp = "overlay_analysis_csharp",
/** Disable TRAP caching when overlay analysis is enabled. */
OverlayAnalysisDisableTrapCaching = "overlay_analysis_disable_trap_caching",
OverlayAnalysisGo = "overlay_analysis_go",
OverlayAnalysisJava = "overlay_analysis_java",
OverlayAnalysisJavascript = "overlay_analysis_javascript",
Expand Down Expand Up @@ -369,11 +367,6 @@ export const featureConfig = {
minimumVersion: CODEQL_OVERLAY_MINIMUM_VERSION_RUBY,
},
// Other overlay-related feature flags
[Feature.OverlayAnalysisDisableTrapCaching]: {
defaultValue: false,
envVar: "CODEQL_ACTION_OVERLAY_ANALYSIS_DISABLE_TRAP_CACHING",
minimumVersion: undefined,
},
[Feature.OverlayAnalysisMatchCodeqlVersion]: {
defaultValue: false,
envVar: "CODEQL_ACTION_OVERLAY_ANALYSIS_MATCH_CODEQL_VERSION",
Expand Down
Loading