Documentation for Strict Environments

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

@@ -178,6 +178,57 @@ 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`
+
+Controls the available environment variables to your tasks.
+
+<Callout type="info">
+  **Warning**: This in experimental flag, so its name and behavior can change.
+</Callout>
+
+| option  | description                                                |
+| ------- | ---------------------------------------------------------- |
+| [blank] | Behaves same as infer                                      |
+| 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`][r-config-experimentalPassThroughEnv] for each
+task config, and
+[`experimentalGlobalPassThroughEnv`][r-config-experimentalGlobalPassThroughEnv]
+in the root of the `turbo.json` config. If either is defined, "strict" mode will
+be inferred. If neither is defined, then `loose` mode is inferred.
+
+`infer` mode is not part of the global cache key, so using the `--experimental-env-mode=infer` (or
+`--experimental-env-mode` without a value) flag will not invalidate the global cache.
+
+**`loose`**
+
+In `loose` mode, all environment variables are made available to the task.
+
+When using this flag, if `experimentalGlobalPassThroughEnv` is set in `turbo.json`, Turborepo
+will invalidate the global cache, as it could change the behavior of all task executions.
+
+**`strict`**
+
+In `strict` mode, only environment variables specified in the following keys are available to
+the task.
+
+- `env` and experimentalPassThroughEnv` in each task
+- `globalEnv` and experimentalGlobalPassThroughEnv` in each task
+
+When using this flag, if `experimentalGlobalPassThroughEnv` is set in `turbo.json`, Turborepo
+will invalidate the global cache, as it could change the behavior of all task executions.
+
+Note that in `strict` mode, (even if it is inferred) _all_ tasks are opted into `strict` mode,
+regardless of whether `experimentalGlobalPassThroughEnv` or `globalEnv` are set.
+
 #### `--filter`
 
 `type: string[]`
@@ -648,3 +699,6 @@ Unlink the current directory from the Remote Cache.
 ## `turbo bin`
 
 Get the path to the `turbo` binary.
+
+[r-config-experimentalPassThroughEnv]: /repo/docs/refernce/configuration#experimentalPassThroughEnv
+[r-config-experimentalGlobalPassThroughEnv]: /repo/docs/refernce/configuration#experimentalGlobalPassThroughEnv

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

@@ -50,11 +50,7 @@ A list of environment variables for implicit global hash dependencies. The conte
 ```jsonc
 {
   "$schema": "https://turbo.build/schema.json",
-  "pipeline": {
-    // ... omitted for brevity
-  },
-
-  "globalEnv": ["GITHUB_TOKEN"] // value will impact the hashes of all tasks
+  "globalEnv": ["VERCEL_ANALYTICS_ID"] // value will impact the hashes of all tasks
 }
 ```
 
@@ -341,3 +337,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/reference/configuration#globalpassthroughenv
+   *
+   * @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/reference/configuration#passthroughenv
+   *
+   * @default []
+   */
+  experimentalPassthroughEnv?: string[];
+
   /**
    * The set of glob patterns indicating a task's cacheable filesystem outputs.
    *