Persist CodeQL version output to file rather than environment by mario-campos · Pull Request #4081 · github/codeql-action

mario-campos · 2026-08-07T20:18:03Z

Currently, the output of codeql version is cached and persisted between steps as an environment variable. This is fine, for now, but, as we begin to cache more of the CLI, we should persist that output to a file instead because:

There are is a limit to the size of a process' environment. On GitHub Actions, the runners already have a populated environment. And, the output of these CLI commands may be verbose.
There is data to suggest that a larger environment has performance implications (more environment variables -> more memory for the kernel to copy during execve(2)).

To that end, and as a precaution, this PR replaces $CODEQL_ACTION_CLI_VERSION_INFO with $CODEQL_ACTION_TEMP/version.json, a file-backed cache for codeql version.

Changes

Moved the CodeQL CLI version caching logic from util.ts (which used environment variables) into a new module src/cli/output-cache.ts, which now uses a temporary on-disk file (codeql-action-command-cache.json) for cross-step persistence. This includes new functions for caching, retrieving, and resetting the cached version, as well as improved validation of persisted data.
Moved the VersionInfo type definition from codeql.ts to a new shared file src/cli/types.ts, and updated all references to use the new location. This centralizes type definitions to avoid cyclic dependencies.
Removed the now-obsolete CODEQL_VERSION_INFO environment variable from EnvVar in environment.ts.

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?

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.

Environments:

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

How did/will you validate this change?

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

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

Moves persisted CodeQL CLI version metadata from an environment variable to a temporary JSON file.

Changes:

Writes and reads version metadata from $CODEQL_ACTION_TEMP/version.json.
Removes the obsolete environment variable.
Updates persistence tests.

Show a summary per file

File	Description
`src/util.ts`	Implements file-based version caching.
`src/util.test.ts`	Updates cache-reading tests.
`src/environment.ts`	Removes the old cache environment variable.

Review details

Files reviewed: 3/3 changed files
Comments generated: 1
Review effort level: Balanced

This is particularly important for the first time that `getCachedCodeQlVersion` is invoked, as this cache file will not yet exist.

mbg

Thanks for picking this back up! I have added a few inline (mostly style) comments.

Some high-level points:

Also added as an in-line comment, but do you plan to have a separate file for each command? If so, why? On the same topic, if not, then should the file be more structured to allow for relevant metadata and other command output down the line?
Have you had any more thoughts about either checking that the cached file is intended for the current analysis (e.g. by checking the generated jobUuid) or deleting cache files on "startup"?
Add a unit test for the case where the file cannot be read (e.g. because it doesn't exist).
The linter CI is failing. Remember to run npm lint locally before committing / pushing changes.

Much more minor, but I spotted this in the PR description:

This is fine, for now, but, as we begin to cache more of the CLI, we should persist that output to a file instead.

The reasoning here ("as we begin to cache more of the CLI") doesn't really justify the conclusion ("we should persist that output to a file instead). Could you edit that to actually highlight why files are preferable to environment variables?

mbg · 2026-08-11T11:32:33Z

+function getPathToCodeQLVersionCacheFile(env: Env): string {
+  return path.join(getTemporaryDirectory(env), "version.json");
+}


Are you planning to have a separate file for each command? If so, why?

No, with this PR, I'm simply trying to do a direct environment-variable-to-file translation. In subsequent PRs, I plan to generalize the file to include additional commands. The only reason that the file's name is associated with the command is to keep this PR focused on this one change, without scope creep of future intentions.

mbg · 2026-08-11T11:33:01Z

+export function cacheCodeQlVersion(
+  cmd: string,
+  version: VersionInfo,
+  env: Env = getEnv(),


Avoid the default getEnv() which could lead to unexpected results.

mbg · 2026-08-11T11:34:34Z

+  let serialized: string;
+  try {
+    serialized = fs.readFileSync(getPathToCodeQLVersionCacheFile(env), "utf8");
+  } catch {


The error here is swallowed, which might make it hard to troubleshoot issues. Consider logging it at debug-level.

Could the logger be instantiated locally within the module or within the function itself? I tried threading it through the call stack, but that would require a lot of modifications (changes to 16+ files).

mbg · 2026-08-11T11:35:00Z

+ */
+export function getCachedCodeQlVersion(
+  cmd?: string,
+  env: Env = getEnv(),


Avoid the default getEnv() which could lead to unexpected results.

Same problem here: threading env through the call stack would require touching a lot of files/functions. Is this still preferable?

mbg · 2026-08-11T11:39:08Z

@@ -535,55 +535,83 @@ test("Failure.orElse returns the default value for a failure result", (t) => {

 test.serial(


This test, and others, probably don't need to be serial anymore since process.env is no longer mutated.

I had the same thought, but Copilot assured me it's still necessary:

Yes, keep .serial() for this one.

Even though this test itself only reads malformed cache entries, it exercises getCachedCodeQlVersion, which depends on the module-global cachedCodeQlVersion state in util.ts. Other nearby tests in the same file can populate that cache, and parallel execution can interleave despite beforeEach resets, since they all share one process/module instance.

So .serial() is the safe choice unless you fully refactor these cache-state tests to avoid shared global state.

The point about cachedCodeQlVersion is fair. That said, I wouldn't be opposed to refactoring that away so that the state is threaded to these functions rather than global as part of this PR.

Agreed, but perhaps best saved for another PR.

Co-authored-by: Michael B. Gale <mbg@github.com>

This brings them out of the crowded all-purpose `util.ts` and into `cli/output-cache.ts` where they are exclusively used.

Persist CodeQL version output to file rather than environment

5f8c44b

Copilot AI balanced review requested due to automatic review settings August 7, 2026 20:18

mario-campos requested a review from a team as a code owner August 7, 2026 20:18

github-actions Bot added the size/S Should be easy to review label Aug 7, 2026

Copilot started reviewing on behalf of mario-campos August 7, 2026 20:18 View session

mario-campos requested a review from mbg August 7, 2026 20:18

Copilot AI reviewed Aug 7, 2026

View reviewed changes

Comment thread src/util.ts Outdated

Handle file-read errors as cache misses

9183a7b

This is particularly important for the first time that `getCachedCodeQlVersion` is invoked, as this cache file will not yet exist.

mario-campos force-pushed the mario-campos/version-cache-to-disk branch from a1f3399 to 9183a7b Compare August 10, 2026 15:45

mbg reviewed Aug 11, 2026

View reviewed changes

mario-campos and others added 5 commits August 11, 2026 11:06

Simplify JSDoc of getCachedCodeQlVersion

208a88a

Co-authored-by: Michael B. Gale <mbg@github.com>

Fix JSDoc of env param

bfcd769

Refactor unit test to extract testing values

0e85c0e

Add test of getCachedCodeQlVersion with no file

bb19330

Introduce basic cli/output-cache.ts module

4dc327a

github-actions Bot added size/L May be hard to review and removed size/S Should be easy to review labels Aug 11, 2026

mario-campos added 4 commits August 11, 2026 15:55

Move cache-related util functions into dedicated module

1332611

Move VersionInfo to dedicated module

246018e

Move VersionInfo-related types to cli/output-cache.ts

0a99875

This brings them out of the crowded all-purpose `util.ts` and into `cli/output-cache.ts` where they are exclusively used.

Update JSDoc of getCachedCodeQlVersion

11569df

mario-campos force-pushed the mario-campos/version-cache-to-disk branch from 139c544 to 11569df Compare August 11, 2026 20:55

mario-campos added 2 commits August 11, 2026 18:09

Generalize file cache data structure

b222c3a

Rename type to better match generic intention

40f80a8

mario-campos force-pushed the mario-campos/version-cache-to-disk branch from b11737e to 40f80a8 Compare August 11, 2026 23:09

		@@ -535,55 +535,83 @@ test("Failure.orElse returns the default value for a failure result", (t) => {

		test.serial(

Uh oh!

Conversation

mario-campos commented Aug 7, 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

Review details

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!

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mario-campos commented Aug 7, 2026 •

edited

Loading

mbg left a comment •

edited

Loading