Delete unused CodeQL bundles from the toolcache before downloading

[henrymercer]

When a job downloads a CodeQL bundle, the toolcache is often already holding a different one that the job will not use, typically the bundle baked into the runner image. On GitHub-hosted runners the toolcache sits on the same filesystem we measure for the disk space check, so that unused bundle takes around 2 GB away from the analysis.

This adds a feature flag, cleanup_toolcache_bundles, that empties $RUNNER_TOOL_CACHE/CodeQL immediately before we download a bundle. It is off by default.

Emptying it before the download rather than after means the space also covers the archive during extraction. We only get as far as downloading when the tools were not resolved from the toolcache, and a lookup there requires both the version directory and its completion marker, so nothing left behind is usable by the job.

That stops holding once a step has obtained the tools, because a later step may run a path it was given, as our own codeql.yml does. The job records that it has the tools and skips the cleanup from then on.

The cleanup only runs when RUNNER_ENVIRONMENT reports github-hosted, so we never delete from a toolcache that outlives the job, and only when the toolcache is on the same filesystem as the workspace, since otherwise the space we free is not space the analysis can use. Windows runner images are laid out that way, keeping the toolcache on C: while the workspace is on D:. Deletion is confined to the CodeQL directory, refuses to follow a symlink, and logs failures rather than throwing.

This also renames isHostedRunner to looksLikeHostedRunner, with no behaviour change. It infers hostedness from the runner name and filesystem layout, so it can disagree with the new isGitHubHostedRunner check. Its callers are deciding whether caching is worthwhile, where the inferred answer is arguably the one they want, so switching them would be a behaviour change and is left for a separate PR.

Risk assessment

• 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?

Workflow types:

• Advanced setup - Impacts users who have custom CodeQL workflows.
• Managed - Impacts users with dynamic workflows (Default Setup, Code Quality, ...).

Products:

• Code Scanning - The changes impact analyses when analysis-kinds: code-scanning.
• Code Quality - The changes impact analyses when analysis-kinds: code-quality.
• Other first-party - The changes impact other first-party analyses.
• Third-party analyses - The changes affect the upload-sarif action.

The cleanup sits on the shared bundle download path, so it can run for anything that obtains the CodeQL tools.

Environments:

• Dotcom - Impacts CodeQL workflows on github.com and/or GitHub Enterprise Cloud with Data Residency.

How did/will you validate this change?

• End-to-end tests - I am depending on PR checks (i.e. tests in pr-checks).
• Unit tests - I am depending on unit test coverage (i.e. tests in .test.ts files).
• Other - Please provide details.

Unit tests cover the flag being off, a non-hosted runner, an unreported runner environment, a toolcache on a different filesystem to the workspace, a hosted runner with bundles present, a download that will not be cached in the toolcache, a step having already obtained the tools, deletion failing, a toolcache we cannot inspect, and a symlinked CodeQL directory. The multi-language PR check runs with the flag enabled, so the cleanup happens ahead of a real build and analysis of seven languages.

This has not been run on a real hosted runner outside the PR checks, and the disk saving is inferred from bundle size rather than measured, so the rollout should confirm it.

If something goes wrong after this change is released, what are the mitigation and rollback strategies?

• Feature flags - All new or changed code paths can be fully disabled with corresponding feature flags.

The rename is not behind the flag, but it has no behaviour change.

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.

A codeql-action/toolcache-bundle-cleanup diagnostic reports which versions were deleted and whether the attempt failed. Note that diagnostics are only flushed by the init action, so a cleanup under the standalone setup-codeql action reports nothing. That is pre-existing behaviour for diagnostics raised from setup-codeql.ts, but it does leave that entry point unmeasurable.

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]

Warning

• Copilot's review of this pull request may be incomplete because some of the changed files are excluded by your Copilot content exclusion settings. See Excluding content from Copilot for details.

Copilot review overview

🟡 Changes recommended

Two moderate issues affect cleanup coverage and failure telemetry.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Balanced
Findings: 2

New issues introduced by this change (2)

Severity	Finding
	src/​setup-codeql.ts — This condition excludes supported explicit tools URLs that do not contain a /codeql-bundle-.../…
	src/​tools-download.ts — The catch also handles permission errors, I/O failures, and other lstat errors, but reports all…

What changed in this PR

Adds feature-flagged cleanup of unused CodeQL toolcache bundles before downloads on GitHub-hosted runners.

Changes:

• Adds guarded toolcache cleanup with telemetry and tests.
• Tracks whether a job already obtained CodeQL tools.
• Clarifies hosted-runner detection APIs.

File	Review
src/​util.ts	Renames and documents the hosted-runner heuristic.
src/​tools-download.ts	Implements cleanup; non-ENOENT inspection errors must be reported as failures.
src/​setup-codeql.ts	Integrates cleanup; the current condition incorrectly excludes some explicit download URLs.
src/​setup-codeql.test.ts	Covers cleanup behavior and safeguards.
src/​feature-flags.ts	Defines the cleanup feature flag.
src/​environment.ts	Adds job-scoped tool acquisition state.
src/​config-utils.ts	Updates renamed heuristic usage.
src/​caching-utils.ts	Updates renamed heuristic usage.
src/​actions-util.ts	Adds service-reported hosted-runner detection.
pr-checks/​checks/​multi-language-autodetect.yml	Enables cleanup in integration checks.

Files excluded by content exclusion policy (2)

• .github/workflows/__multi-language-autodetect.yml
• lib/entry-points.js

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mbg]

This mostly looks good and makes a lot of sense, thank you! I don't think I noticed anything overly critical, but found a few minor-ish points, some of which we should probably address.

[mbg]

To be a bit extra safe, do you think it would make sense to perform the symlink check for each of the specific version directories as well before deleting them individually to make sure that the specific version directories aren't symlinks?

[henrymercer]

This would be odd on a runner that claims to be GitHub-hosted, but can do. In most cases this shouldn't slow things down much as we expect exactly one CodeQL entry in the toolcache.

[mbg]

Minor: Consider putting ${toolDirectory} in quotes to clearly delimit the start and end of the value. Similarly elsewhere in log messages.

[mbg]

Minor: Would be nice if this used ActionState<["Logger", "Features"]>. Although not available at the call site, you can just pass { logger, features } in there.

[mbg]

If following the suggestion for ActionState above, add Env/ReadOnlyEnv to the list of state features. Otherwise add either as an explicit parameter. Then use (action.)env.getOptional instead of the deprecated getOptionalEnvVar. Use getEnv() as argument to tryDeleteToolcacheBundles if needed.

[mbg]

I think this will mostly just always result in a redundant log message since most of the body of deleteToolcacheBundles is wrapped in its own try/catch blocks with appropriate log messages. Consider whether:

• The call to getToolcacheToolDirectory in deleteToolcacheBundles could be wrapped in its own try/catch to avoid this one here; or
• The entire body of deleteToolcacheBundles could be wrapped in one; or
• The existing catch blocks in deleteToolcacheBundles should log at debug level instead.

[mbg]

I am wondering a bit about the logic / naming of this. The name implies that we have obtained our own bundle (and stored it in the toolcache), but that's not necessarily what would have happened if we reach this point (e.g. because the bundle was already in the toolcache).

Consider whether it would be better to name this environment variable something else that's more representative of the logic here (e.g. HAS_SETUP_CODEQL) so that we (or someone unfamiliar with this) don't get confused/mislead when reviewing logs that contain a HAS_OBTAINED_CODEQL_TOOLS=true or only set this environment variable if we have actually obtained our own bundle.

[mbg]

Minor: Change this to be more descriptive of what the test actually does, i.e. checks that we assume the toolcache is not on the same filesystem if we can't tell.