Allow abstracting over process.env

mbg · Jul 7, 2026 · Jun 16, 2026 · Jun 16, 2026 · Jun 23, 2026 · Jun 23, 2026
commit 652296eb9e76be692cbe3c9faa47dec498736254
diff --git a/src/environment.ts b/src/environment.ts
@@ -160,3 +160,11 @@ export enum EnvVar {
   /** Used by Code Scanning Risk Assessment to communicate the assessment ID to the CodeQL Action. */
   RISK_ASSESSMENT_ID = "CODEQL_ACTION_RISK_ASSESSMENT_ID",
 }
+
+/** A wrapper around an environment, to allow abstracting away from `process.env` in tests. */
+export interface Env {
+  /** Tries to get the value for `name` and throws if there isn't one. */
+  getRequired(name: string): string;
+  /** Gets the value for `name`, or `undefined` if it isn't set or empty. */
+  getOptional(name: string): string | undefined;
+}
@@ -18,6 +18,7 @@ import { CachingKind } from "./caching-utils";
 import * as codeql from "./codeql";
 import { Config } from "./config-utils";
 import * as defaults from "./defaults.json";
+import { Env } from "./environment";
 import {
   CodeQLDefaultVersionInfo,
   Feature,
@@ -29,6 +30,7 @@ import { OverlayDatabaseMode } from "./overlay/overlay-database-mode";
 import {
   DEFAULT_DEBUG_ARTIFACT_NAME,
   DEFAULT_DEBUG_DATABASE_NAME,
+  getEnv,
   GitHubVariant,
   GitHubVersion,
   HTTPError,
@@ -172,6 +174,11 @@ export function makeMacro<Args extends unknown[]>(
   return wrapper;
 }
 
+export function getTestEnv(): Env {
+  const testEnv: NodeJS.ProcessEnv = {};
+  return getEnv(testEnv);
+}
+
 /**
  * Gets an `ActionsEnv` instance for use in tests.
  */

diff --git a/src/util.ts b/src/util.ts
@@ -13,7 +13,7 @@ import * as apiCompatibility from "./api-compatibility.json";
 import type { CodeQL, VersionInfo } from "./codeql";
 import type { Pack } from "./config/db-config";
 import type { Config } from "./config-utils";
-import { EnvVar } from "./environment";
+import { Env, EnvVar } from "./environment";
 import * as json from "./json";
 import { Language } from "./languages";
 import { Logger } from "./logging";
@@ -566,28 +566,56 @@ export function initializeEnvironment(version: string) {
   core.exportVariable(EnvVar.VERSION, version);
 }
 
+/** Gets an `Env` instance for `env`, which is `process.env` by default. */
+export function getEnv(env: NodeJS.ProcessEnv = process.env): Env {
+  return {
+    getRequired: (name) => getRequiredEnvVar(env, name),
+    getOptional: (name) => getOptionalEnvVar(name),
+  };
+}
+
 /**
- * Get an environment parameter, but throw an error if it is not set.
+ * Gets an environment variable, but throws an error if it is not set.
  */
-export function getRequiredEnvParam(paramName: string): string {
-  const value = process.env[paramName];
+export function getRequiredEnvVar(
+  env: NodeJS.ProcessEnv,
+  paramName: string,
+): string {
+  const value = env[paramName];
   if (value === undefined || value.length === 0) {
     throw new Error(`${paramName} environment variable must be set`);
   }
   return value;
 }
 
 /**
- * Get an environment variable, but return `undefined` if it is not set or empty.
+ * Get an environment parameter, but throw an error if it is not set.
  */
-export function getOptionalEnvVar(paramName: string): string | undefined {
-  const value = process.env[paramName];
+export function getRequiredEnvParam(paramName: string): string {
+  return getRequiredEnvVar(process.env, paramName);
+}
+
+/**
+ * Gets an environment variable, but returns `undefined` if it is not set or empty.
+ */
+export function getOptionalEnvVarFrom(
+  env: NodeJS.ProcessEnv,
+  paramName: string,
+): string | undefined {
+  const value = env[paramName];
   if (value?.trim().length === 0) {
     return undefined;
   }
   return value;
 }
 
+/**
+ * Get an environment variable, but return `undefined` if it is not set or empty.
+ */
+export function getOptionalEnvVar(paramName: string): string | undefined {
+  return getOptionalEnvVarFrom(process.env, paramName);
+}
+
 export class HTTPError extends Error {
   public status: number;