Documentation for Strict Environments

docs/pages/repo/docs/reference/command-line-reference.mdx

@@ -178,6 +178,55 @@ Task details include:
 - `dependencies`: Tasks that must run before this task
 - `dependents`: Tasks that must be run after this task
 
+#### `--experimental-env-mode`
+
+`type: string`
+
+<Callout type="info">
+  **Warning**: This is an experimental flag, so its name and behavior can change.
+</Callout>
+
+Controls the available environment variables to your tasks.
+
+| option | description                                                |
+| ------ | ---------------------------------------------------------- |
+| infer  | infers strict mode or loose mode based on allowlist config |
+| loose  | allows all environment variables                           |
+| strict | only allow declared variables                              |
+
+`PATH`, `SHELL`, and `SYSTEMROOT` are always available to all tasks.
+
+##### `infer`
+
+In infer mode, Turborepo will look for [`experimentalPassThroughEnv`][1] for
+each task config, and [`experimentalGlobalPassThroughEnv`][2] in the root of the
+`turbo.json` config. If either is defined, "strict" mode is inferred. If
+neither is defined, then `loose` mode is inferred.
+
+In this mode, the value of `experimentalGlobalPassThroughEnv` and the flag's
+value ("infer") will only be incorporated into the global hash if
+`experimentalGlobalPassThroughEnv` is set.
+
+##### `loose`
+
+In loose mode, all environment variables are made available to the task.
+The value of `experimentalGlobalPassThroughEnv` and the flag's value ("loose")
+itself will be incorporated into the global hash.
+
+##### `strict`
+
+In strict mode, only environment variables specified in the following keys are
+available to the task:
+
+- `env` and `experimentalPassThroughEnv` in each task configuration
+- `globalEnv` and `experimentalGlobalPassThroughEnv` in the root of your config
+
+The value of `experimentalGlobalPassThroughEnv` and the flag's value ("strict")
+itself will be incorporated into the global hash.
+
+If strict mode is specified or inferred, _all_ tasks are run in strict mode,
+regardless of their configuration.
+
 #### `--filter`
 
 `type: string[]`
@@ -648,3 +697,6 @@ Unlink the current directory from the Remote Cache.
 ## `turbo bin`
 
 Get the path to the `turbo` binary.
+
+[1]: /repo/docs/refernce/configuration#experimentalPassThroughEnv
+[2]: /repo/docs/refernce/configuration#experimentalGlobalPassThroughEnv

docs/pages/repo/docs/reference/configuration.mdx

@@ -341,3 +341,65 @@ option, `turbo` can warn you about an invalid configuration.
 ```
 
 [1]: /repo/docs/core-concepts/monorepos/configuring-workspaces
+
+## Experimental
+
+### `experimentalGlobalPassThroughEnv`
+
+This goes at the root of your configuration.
+
+`type: string[]`
+
+An allowlist of environment variables that should be made available to all tasks
+but should not contribute to the task's cache key. Using this key opts all tasks
+into strict environment variable mode.
+
+Changing this list will contribute to the global cache key, but the value of each
+variable will not.
+
+**Example**
+
+`AWS_SECRET_KEY` and `GITHUB_TOKEN` are available to all tasks in `strict` [env mode][r-cli-env-mode].
+
+```jsonc
+{
+  "$schema": "https://turbo.build/schema.json",
+  "experimentalGlobalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"],
+  "pipeline": {
+    // ...task definitions...
+  }
+}
+```
+
+### `experimentalPassThroughEnv`
+
+`type: string[]`
+
+This config goes inside each task definition in the [`pipeline`][r-config-pipeline].
+
+An allowlist of environment variables that should be made available to this task
+but should not contribute to the task's cache key. Using this key opts this task
+into strict environment variable mode.
+
+Changing this list will contribute to the task's cache key, but the value of each
+variable will not.
+
+**Example**
+
+`AWS_SECRET_KEY` and `GITHUB_TOKEN` are available to the `build` task, but not to the `lint` task
+in `strict` [env mode][r-cli-env-mode].
+
+```jsonc
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "experimentalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
+    },
+    "lint": {},
+  }
+}
+```
+
+[r-config-pipeline]: #pipeline
+[r-cli-env-mode]: /repo/docs/reference/command-line-reference#--experimental-env-mode

packages/turbo-types/src/types/config.ts

@@ -71,6 +71,18 @@ export interface RootSchema extends BaseSchema {
    */
   globalEnv?: string[];
 
+  /**
+   * An allowlist of environment variables that should be made to all tasks, but
+   * should not contribute to the task's cache key, e.g. `AWS_SECRET_KEY`.
+   *
+   * Only applies in `--env=strict` mode.
+   *
+   * Documentation: https://turbo.build/repo/docs/refernce/configuration#experimentalGlobalPassThroughEnv
+   *
+   * @default []
+   */
+  experimentalGlobalPassThroughEnv?: string[];
+
   /**
    * Configuration options that control how turbo interfaces with the remote cache.
    *
@@ -114,6 +126,19 @@ export interface Pipeline {
    */
   env?: string[];
 
+  /**
+   * An allowlist of environment variables that should be made available in this
+   * task's environment, but should not contribute to the task's cache key,
+   * e.g. `AWS_SECRET_KEY`.
+   *
+   * Only applies in `--env=strict` mode.
+   *
+   * Documentation: https://turbo.build/repo/docs/refernce/configuration#experimentalPassThroughEnv
+   *
+   * @default []
+   */
+  experimentalPassThroughEnv?: string[];
+
   /**
    * The set of glob patterns indicating a task's cacheable filesystem outputs.
    *