diff --git a/docs/pages/repo/docs/reference/command-line-reference.mdx b/docs/pages/repo/docs/reference/command-line-reference.mdx index f0c9387e64757..b1fdddf793ea9 100644 --- a/docs/pages/repo/docs/reference/command-line-reference.mdx +++ b/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` + + + **Warning**: This is an experimental flag, so its name and behavior can change. + + +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[]` @@ -659,3 +708,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 diff --git a/docs/pages/repo/docs/reference/configuration.mdx b/docs/pages/repo/docs/reference/configuration.mdx index c969a1909c5cc..ef52d46411f41 100644 --- a/docs/pages/repo/docs/reference/configuration.mdx +++ b/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 diff --git a/packages/turbo-types/src/types/config.ts b/packages/turbo-types/src/types/config.ts index 39641d2a45b68..1a3b3ccc1f952 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/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. *