diff --git a/docs/pages/repo/docs/reference/command-line-reference.mdx b/docs/pages/repo/docs/reference/command-line-reference.mdx index 09e14923f4698..324f625cf9ef5 100644 --- a/docs/pages/repo/docs/reference/command-line-reference.mdx +++ b/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. + + + **Warning**: This in experimental flag, so its name and behavior can change. + + +| 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 diff --git a/docs/pages/repo/docs/reference/configuration.mdx b/docs/pages/repo/docs/reference/configuration.mdx index c969a1909c5cc..b25d0f387221b 100644 --- a/docs/pages/repo/docs/reference/configuration.mdx +++ b/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 diff --git a/packages/turbo-types/src/types/config.ts b/packages/turbo-types/src/types/config.ts index 39641d2a45b68..d21c2a04d3f03 100644 --- a/packages/turbo-types/src/types/config.ts +++ b/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. *