Delete unused CodeQL bundles from the toolcache before downloading

CHANGELOG.md

@@ -4,6 +4,7 @@ See the [releases page](https://github.com/github/codeql-action/releases) for th
 
 ## [UNRELEASED]
 
+- On GitHub-hosted runners, the CodeQL Action now deletes unused CodeQL bundles from the toolcache before downloading a different bundle, which frees up disk space for the analysis. We expect to roll this change out to everyone in September. [#4124](https://github.com/github/codeql-action/pull/4124)
 - The CodeQL Action now supports CodeQL releases that are compatible with Linux Arm64 and downloads the native `linux-arm64` CodeQL bundle when available. [#4072](https://github.com/github/codeql-action/pull/4072)
 
 ## 4.37.9 - 26 Aug 2026

pr-checks/checks/multi-language-autodetect.yml

@@ -15,6 +15,7 @@ operatingSystems:
       - stable-v2.21.4
       - stable-v2.22.4
 env:
+  CODEQL_ACTION_CLEANUP_TOOLCACHE_BUNDLES: true
   CODEQL_ACTION_RESOLVE_SUPPORTED_LANGUAGES_USING_CLI: true
 installGo: true
 installDotNet: true

src/actions-util.ts

@@ -283,6 +283,19 @@ export function isSelfHostedRunner(env: Env = getEnv()) {
   return env.getOptional(ActionsEnvVars.RUNNER_ENVIRONMENT) === "self-hosted";
 }
 
+/**
+ * Whether the job is running on a runner that GitHub hosts, and whose toolcache is therefore thrown
+ * away once the job has finished.
+ *
+ * Unlike `looksLikeHostedRunner`, this is based on what the service reports for the job rather than
+ * on how the runner's filesystem happens to be laid out, so it does not match self-hosted runners
+ * that are configured to resemble hosted ones, such as those that mount a persistent volume at
+ * `/opt/hostedtoolcache`.
+ */
+export function isGitHubHostedRunner(env: Env = getEnv()) {
+  return env.getOptional(ActionsEnvVars.RUNNER_ENVIRONMENT) === "github-hosted";
+}
+
 /** Determines whether the workflow trigger is `dynamic`. */
 export function isDynamicWorkflow(env: Env = getEnv()): boolean {
   return getWorkflowEventName(env) === "dynamic";

src/caching-utils.ts

@@ -5,7 +5,7 @@ import * as core from "@actions/core";
 import { getOptionalInput, isDefaultSetup } from "./actions-util";
 import { EnvVar } from "./environment";
 import { Logger } from "./logging";
-import { isHostedRunner, tryGetFolderBytes } from "./util";
+import { looksLikeHostedRunner, tryGetFolderBytes } from "./util";
 
 /**
  * Returns the total size of all the specified paths.
@@ -109,7 +109,7 @@ export function getDependencyCachingEnabled(): CachingKind {
   if (dependencyCaching !== undefined) return getCachingKind(dependencyCaching);
 
   // On self-hosted runners which may have dependencies installed centrally, disable caching by default
-  if (!isHostedRunner()) return CachingKind.None;
+  if (!looksLikeHostedRunner()) return CachingKind.None;
 
   // Disable in advanced workflows by default.
   if (!isDefaultSetup()) return CachingKind.None;

src/config-utils.ts

@@ -90,9 +90,8 @@ import {
   Result,
   Success,
   Failure,
-  isHostedRunner,
+  looksLikeHostedRunner,
 } from "./util";
-
 export { type Config } from "./config/action-config";
 
 /**
@@ -938,7 +937,7 @@ export async function isTrapCachingEnabled(
   if (trapCaching !== undefined) return trapCaching === "true";
 
   // On self-hosted runners which may have slow network access, disable TRAP caching by default.
-  if (!isHostedRunner()) return false;
+  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.

src/environment.ts

@@ -63,6 +63,12 @@ export enum EnvVar {
   /** Whether the CodeQL Action has already warned the user about low disk space. */
   HAS_WARNED_ABOUT_DISK_SPACE = "CODEQL_ACTION_HAS_WARNED_ABOUT_DISK_SPACE",
 
+  /**
+   * Whether a step in this job has already set up CodeQL. Steps that run afterwards may be holding
+   * a path into the toolcache, so we must not delete anything from it.
+   */
+  HAS_SET_UP_CODEQL = "CODEQL_ACTION_HAS_SET_UP_CODEQL",
+
   /** Whether the `setup-codeql` action has been run. */
   SETUP_CODEQL_ACTION_HAS_RUN = "CODEQL_ACTION_SETUP_CODEQL_HAS_RUN",
 

src/feature-flags.ts

@@ -74,6 +74,11 @@ export enum Feature {
   AllowMergeConfigFiles = "allow_merge_config_files",
   /** Controls whether we allow multiple values for the `analysis-kinds` input. */
   AllowMultipleAnalysisKinds = "allow_multiple_analysis_kinds",
+  /**
+   * Controls whether we delete CodeQL bundles that we are not going to use from the toolcache
+   * before downloading a different bundle, in order to reclaim disk space.
+   */
+  CleanupToolcacheBundles = "cleanup_toolcache_bundles",
   CleanupTrapCaches = "cleanup_trap_caches",
   /** Whether to allow the `config-file` input to be specified via a repository property. */
   ConfigFileRepositoryProperty = "config_file_repository_property",
@@ -211,6 +216,11 @@ export const featureConfig = {
     envVar: "CODEQL_ACTION_ALLOW_MULTIPLE_ANALYSIS_KINDS",
     minimumVersion: undefined,
   },
+  [Feature.CleanupToolcacheBundles]: {
+    defaultValue: false,
+    envVar: "CODEQL_ACTION_CLEANUP_TOOLCACHE_BUNDLES",
+    minimumVersion: undefined,
+  },
   [Feature.CleanupTrapCaches]: {
     defaultValue: false,
     envVar: "CODEQL_ACTION_CLEANUP_TRAP_CACHES",