Add trimRushEnvironmentVariablesForOperations experiment

Co-authored-by: iclanton <5010588+iclanton@users.noreply.github.com>

Author: Copilot

common/changes/@microsoft/rush-lib/trim-rush-env-vars-experiment_2026-08-28-05-20.json

@@ -0,0 +1,9 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush-lib",
+      "comment": "Add a new `trimRushEnvironmentVariablesForOperations` experiment that, when enabled, omits environment variables whose names begin with `RUSH_` from the environment forwarded to operation processes (e.g. \"build\", \"test\").",
+      "type": "minor"
+    }
+  ]
+}

common/reviews/api/rush-lib.api.md

@@ -491,6 +491,7 @@ export interface IExperimentsJson {
     printEventHooksOutputToConsole?: boolean;
     rushAlerts?: boolean;
     strictChangefileValidation?: boolean;
+    trimRushEnvironmentVariablesForOperations?: boolean;
     useDirectFileTransfersForBuildCache?: boolean;
     useIPCScriptsInWatchMode?: boolean;
     usePnpmFrozenLockfileForRushInstall?: boolean;

libraries/rush-lib/src/api/ExperimentsConfiguration.ts

@@ -153,6 +153,15 @@ export interface IExperimentsJson {
    * effect; otherwise it falls back to the buffer-based approach.
    */
   useDirectFileTransfersForBuildCache?: boolean;
+
+  /**
+   * By default, Rush forwards its entire process environment (minus a small denylist) to the shell
+   * commands it invokes for operations (e.g. "build", "test"). If true, environment variables whose
+   * names begin with `RUSH_` will additionally be omitted from that forwarded environment. This can
+   * help prevent operation scripts from accidentally depending on Rush's own internal environment
+   * variables.
+   */
+  trimRushEnvironmentVariablesForOperations?: boolean;
 }
 
 const _EXPERIMENTS_JSON_SCHEMA: JsonSchema = JsonSchema.fromLoadedObject(schemaJson);

libraries/rush-lib/src/cli/scriptActions/PhasedScriptAction.ts

@@ -59,6 +59,7 @@ import { getVariantAsync, VARIANT_PARAMETER } from '../../api/Variants';
 import { Selection } from '../../logic/Selection';
 import { NodeDiagnosticDirPlugin } from '../../logic/operations/NodeDiagnosticDirPlugin';
 import { IgnoredParametersPlugin } from '../../logic/operations/IgnoredParametersPlugin';
+import { TrimRushEnvironmentVariablesPlugin } from '../../logic/operations/TrimRushEnvironmentVariablesPlugin';
 import { DebugHashesPlugin } from '../../logic/operations/DebugHashesPlugin';
 import { measureAsyncFn, measureFn } from '../../utilities/performance';
 
@@ -404,6 +405,14 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
       // Verifies correctness of rush-project.json entries for the graph
       new ValidateOperationsPlugin(terminal).apply(hooks);
 
+      if (
+        this.rushConfiguration.experimentsConfiguration.configuration
+          .trimRushEnvironmentVariablesForOperations
+      ) {
+        // Trim RUSH_-prefixed environment variables before forwarding to operation processes
+        new TrimRushEnvironmentVariablesPlugin().apply(hooks);
+      }
+
       // Forward ignored parameters to child processes as an environment variable
       new IgnoredParametersPlugin().apply(hooks);
 

libraries/rush-lib/src/logic/operations/TrimRushEnvironmentVariablesPlugin.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import type { IPhasedCommandPlugin, PhasedCommandHooks } from '../../pluginFramework/PhasedCommandHooks';
+import type { IEnvironment } from '../../utilities/Utilities';
+
+const PLUGIN_NAME: 'TrimRushEnvironmentVariablesPlugin' = 'TrimRushEnvironmentVariablesPlugin';
+
+/**
+ * Prefix used by environment variables that Rush itself defines and consumes.
+ */
+const RUSH_ENVIRONMENT_VARIABLE_NAME_PREFIX: 'RUSH_' = 'RUSH_';
+
+/**
+ * Phased command plugin that removes environment variables whose names begin with `RUSH_` before
+ * they are forwarded to operation processes. Enabled via the `trimRushEnvironmentVariablesForOperations`
+ * experiment in experiments.json.
+ */
+export class TrimRushEnvironmentVariablesPlugin implements IPhasedCommandPlugin {
+  public apply(hooks: PhasedCommandHooks): void {
+    hooks.onGraphCreatedAsync.tap(PLUGIN_NAME, (graph) => {
+      graph.hooks.createEnvironmentForOperation.tap(PLUGIN_NAME, (env: IEnvironment) => {
+        for (const key of Object.getOwnPropertyNames(env)) {
+          if (key.toUpperCase().startsWith(RUSH_ENVIRONMENT_VARIABLE_NAME_PREFIX)) {
+            delete env[key];
+          }
+        }
+
+        return env;
+      });
+    });
+  }
+}

libraries/rush-lib/src/logic/operations/test/TrimRushEnvironmentVariablesPlugin.test.ts

@@ -0,0 +1,102 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import path from 'node:path';
+import { JsonFile } from '@rushstack/node-core-library';
+
+import { RushConfiguration } from '../../../api/RushConfiguration';
+import { CommandLineConfiguration, type IPhasedCommandConfig } from '../../../api/CommandLineConfiguration';
+import type { Operation } from '../Operation';
+import type { ICommandLineJson } from '../../../api/CommandLineJson';
+import { PhasedOperationPlugin } from '../PhasedOperationPlugin';
+import { ShellOperationRunnerPlugin } from '../ShellOperationRunnerPlugin';
+import { TrimRushEnvironmentVariablesPlugin } from '../TrimRushEnvironmentVariablesPlugin';
+import {
+  type ICreateOperationsContext,
+  type IOperationGraphContext,
+  PhasedCommandHooks
+} from '../../../pluginFramework/PhasedCommandHooks';
+import type { IOperationGraph } from '../IOperationGraph';
+import { OperationGraphHooks } from '../../../pluginFramework/OperationGraphHooks';
+import type { IEnvironment } from '../../../utilities/Utilities';
+import type { IOperationRunnerContext } from '../IOperationRunner';
+import type { IOperationExecutionResult } from '../IOperationExecutionResult';
+
+/**
+ * Helper function to create a minimal mock record for testing the createEnvironmentForOperation hook
+ */
+function createMockRecord(operation: Operation): IOperationRunnerContext & IOperationExecutionResult {
+  return {
+    operation,
+    environment: undefined
+  } as IOperationRunnerContext & IOperationExecutionResult;
+}
+
+describe(TrimRushEnvironmentVariablesPlugin.name, () => {
+  it('should remove RUSH_-prefixed environment variables while preserving others', async () => {
+    const rushJsonFile: string = path.resolve(__dirname, `../../test/parameterIgnoringRepo/rush.json`);
+    const commandLineJsonFile: string = path.resolve(
+      __dirname,
+      `../../test/parameterIgnoringRepo/common/config/rush/command-line.json`
+    );
+
+    const rushConfiguration = RushConfiguration.loadFromConfigurationFile(rushJsonFile);
+    const commandLineJson: ICommandLineJson = JsonFile.load(commandLineJsonFile);
+
+    const commandLineConfiguration = new CommandLineConfiguration(commandLineJson);
+    const buildCommand: IPhasedCommandConfig = commandLineConfiguration.commands.get(
+      'build'
+    )! as IPhasedCommandConfig;
+
+    const fakeCreateOperationsContext: Pick<
+      ICreateOperationsContext,
+      'phaseSelection' | 'projectSelection' | 'projectConfigurations' | 'rushConfiguration'
+    > = {
+      phaseSelection: buildCommand.phases,
+      projectSelection: new Set(rushConfiguration.projects),
+      projectConfigurations: new Map(),
+      rushConfiguration
+    };
+
+    const hooks: PhasedCommandHooks = new PhasedCommandHooks();
+
+    // Apply plugins
+    new PhasedOperationPlugin().apply(hooks);
+    new ShellOperationRunnerPlugin().apply(hooks);
+    new TrimRushEnvironmentVariablesPlugin().apply(hooks);
+
+    const operations: Set<Operation> = await hooks.createOperationsAsync.promise(
+      new Set(),
+      fakeCreateOperationsContext as unknown as ICreateOperationsContext
+    );
+
+    // Set up a mock graph and invoke onGraphCreatedAsync so the plugin registers its graph hooks
+    const graphHooks: OperationGraphHooks = new OperationGraphHooks();
+    const fakeGraph: IOperationGraph = { hooks: graphHooks } as unknown as IOperationGraph;
+    await hooks.onGraphCreatedAsync.promise(
+      fakeGraph,
+      fakeCreateOperationsContext as unknown as IOperationGraphContext
+    );
+
+    const operation = Array.from(operations)[0];
+    expect(operation).toBeDefined();
+
+    const mockRecord = createMockRecord(operation);
+
+    const initialEnvironment: IEnvironment = {
+      ...process.env,
+      RUSH_TEMP_FOLDER: 'some-temp-folder',
+      Rush_Some_Mixed_Case_Var: 'should also be trimmed',
+      RUSHSTACK_FILE_ERROR_BASE_FOLDER: 'should be preserved',
+      PATH: process.env.PATH,
+      SOME_OTHER_VAR: 'should be preserved'
+    };
+
+    const env: IEnvironment = graphHooks.createEnvironmentForOperation.call(initialEnvironment, mockRecord);
+
+    expect(env.RUSH_TEMP_FOLDER).toBeUndefined();
+    expect(env.Rush_Some_Mixed_Case_Var).toBeUndefined();
+    expect(env.RUSHSTACK_FILE_ERROR_BASE_FOLDER).toBe('should be preserved');
+    expect(env.SOME_OTHER_VAR).toBe('should be preserved');
+  });
+});

libraries/rush-lib/src/schemas/experiments.schema.json

@@ -93,6 +93,10 @@
     "useDirectFileTransfersForBuildCache": {
       "description": "If true, the build cache will use file-based APIs to transfer cache entries to and from cloud storage. This avoids loading the entire cache entry into memory, which can prevent out-of-memory errors for large build outputs and allow cache entries to exceed the limit of a single Buffer. The cloud cache provider plugin must implement the optional file-based methods for this to take effect; otherwise it falls back to the buffer-based approach.",
       "type": "boolean"
+    },
+    "trimRushEnvironmentVariablesForOperations": {
+      "description": "By default, Rush forwards its entire process environment (minus a small denylist) to the shell commands it invokes for operations (e.g. 'build', 'test'). If true, environment variables whose names begin with `RUSH_` will additionally be omitted from that forwarded environment. This can help prevent operation scripts from accidentally depending on Rush's own internal environment variables.",
+      "type": "boolean"
     }
   },
   "additionalProperties": false