Update docs on declaring env key dependencies (#1936)

Docs for `env` key updates

- [x] #1970
- [x] #1950
- [ ] codemod
- [ ] lint rule


This PR will include: 

- guide and reference docs updates
- blog post

This PR will be ready for review after all the code pieces are merged.

Co-authored-by: Thomas Knickman <2933988+tknickman@users.noreply.github.com>

docs/pages/docs/core-concepts/caching.mdx

@@ -189,69 +189,67 @@ Otherwise, you could ship a cached build with the wrong environment variables!
 You can control `turbo`'s caching behavior based on
 the values of environment variables:
 
-- Including environment variables in a `dependsOn` in your `pipeline` definition prefixed by a `$` will impact the cache fingerprint on a per-task or per-workspace-task basis.
+- Including environment variables in the `env` key in your `pipeline` definition will impact the cache fingerprint on a per-task or per-workspace-task basis.
 - The value of any environment variable that includes `THASH` in its name will impact the cache fingerprint of _all_ tasks.
 
 ```jsonc
 {
   "$schema": "https://turborepo.org/schema.json",
   "pipeline": {
     "build": {
-      "dependsOn": [
-        "^build",
-        // env vars will impact hashes of all "build" tasks
-        "$SOME_ENV_VAR",
-      ],
+      "dependsOn": ["^build"],
+      // env vars will impact hashes of all "build" tasks
+      "env": ["SOME_ENV_VAR"],
       "outputs": ["dist/**"]
     },
 
     // override settings for the "build" task for the "web" app
     "web#build": {
-      "dependsOn": [
-        "^build",
+      "dependsOn": ["^build"],
+      "env": [
         // env vars that will impact the hash of "build" task for only "web" app
-        "$STRIPE_SECRET_KEY",
-        "$NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
-        "$NEXT_PUBLIC_ANALYTICS_ID",
+        "STRIPE_SECRET_KEY",
+        "NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
+        "NEXT_PUBLIC_ANALYTICS_ID"
       ],
       "outputs": [".next/**"],
     },
   }
 }
 ```
 
+<Callout type="info">
+  Declaring environment variables in the `dependsOn` config with a `$` prefix is deprecated.
+</Callout>
+
 To alter the cache for _all_ tasks, you can declare environment variables in the
-`globalDependencies` array:
+`globalEnv` array:
 
 ```diff
 {
   "$schema": "https://turborepo.org/schema.json",
   "pipeline": {
     "build": {
-      "dependsOn": [
-        "^build",
-        // env vars will impact hashes of all "build" tasks
-        "$SOME_ENV_VAR",
-      ],
+      "dependsOn": ["^build"],
+      // env vars will impact hashes of all "build" tasks
+      "env": ["SOME_ENV_VAR"],
       "outputs": ["dist/**"]
     },
 
     // override settings for the "build" task for the "web" app
     "web#build": {
-      "dependsOn": [
-        "^build",
+      "dependsOn": ["^build"],
+      "env": [
         // env vars that will impact the hash of "build" task for only "web" app
-        "$STRIPE_SECRET_KEY",
-        "$NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
-        "$NEXT_PUBLIC_ANALYTICS_ID",
+        "STRIPE_SECRET_KEY",
+        "NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
+        "NEXT_PUBLIC_ANALYTICS_ID"
       ],
       "outputs": [".next/**"],
     },
   },
-+  "globalDependencies": [
-+    "$GITHUB_TOKEN",// env var that will impact the hashes of all tasks,
-+    "tsconfig.json", // file contents will impact the hashes of all tasks,
-+    ".env.*", // glob file contents will impact the hashes of all tasks,
++  "globalEnv": [
++    "GITHUB_TOKEN" // env var that will impact the hashes of all tasks,
 +  ]
 }
 ```
@@ -268,9 +266,9 @@ To help ensure correct caching across environments Turborepo 1.4+ will automatic
 {
   "pipeline": {
     "build": {
-      "dependsOn": [
-        "^build"
--       "$NEXT_PUBLIC_EXAMPLE_ENV_VAR"
+      "dependsOn": ["^build"],
+      "env": [
+-       "NEXT_PUBLIC_EXAMPLE_ENV_VAR"
       ]
     }
   }

docs/pages/docs/reference/codemods.mdx

@@ -125,3 +125,67 @@ Run the codemod:
 ```sh
 npx @turbo/codemod create-turbo-config
 ```
+
+### `migrate-env-var-dependencies`
+
+Migrates all environment variable dependencies in `turbo.json` from `dependsOn` and `globalDependencies` to `env` and `globalEnv` respecively.
+
+For example:
+
+```json
+// Before, turbo.json
+{
+  "$schema": "https://turborepo.org/schema.json",
+  "globalDependencies": [".env", "$CI_ENV"],
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build", "$API_BASE"],
+      "outputs": [".next/**"]
+    },
+    "lint": {
+      "outputs": []
+    },
+    "dev": {
+      "cache": false
+    }
+  }
+}
+
+```
+
+````diff
+// After, turbo.json
+{
+  "$schema": "https://turborepo.org/schema.json",
+- "globalDependencies": [".env", "$CI_ENV"],
++ "globalDependencies": [".env"],
++ "globalEnv": ["CI_ENV"],
+  "pipeline": {
+    "build": {
+-     "dependsOn": ["^build", "$API_BASE"],
++     "dependsOn": ["^build"],
++     "env": ["API_BASE"],
+      "outputs": [".next/**"],
+    },
+    "lint": {
+      "outputs": []
+    },
+    "dev": {
+      "cache": false
+    }
+  }
+}
+
+#### Usage
+
+Go to your project:
+
+```sh
+cd path-to-your-turborepo/
+````
+
+Run the codemod:
+
+```sh
+npx @turbo/codemod migrate-env-var-dependencies
+```

docs/pages/docs/reference/configuration.mdx

@@ -29,8 +29,8 @@ This is useful for busting the cache based on `.env` files (not in Git), environ
   "globalDependencies": [
     ".env", // contents will impact hashes of all tasks
     "tsconfig.json", // contents will impact hashes of all tasks
-    "$GITHUB_TOKEN"// value will impact the hashes of all tasks
-  ]
+  ],
+  "globalEnv": ["GITHUB_TOKEN"] // value will impact the hashes of all tasks
 }
 ```
 
@@ -64,15 +64,20 @@ Each key in the `pipeline` object is the name of a task that can be executed by
 
 `type: string[]`
 
-The list of tasks and environment variables that this task depends on.
+The list of tasks this task depends on.
 
 Prefixing an item in `dependsOn` with a `^` tells `turbo` that this pipeline task depends on the workspace's topological dependencies completing the task with the `^` prefix first (e.g. "a workspace's `build` tasks should only run once all of its `dependencies` and `devDependencies` have completed their own `build` commands").
 
 Items in `dependsOn` without `^` prefix, express the relationships between tasks at the workspace level (e.g. "a workspace's `test` and `lint` commands depend on `build` being completed first").
 
 Prefixing an item in `dependsOn` with a `$` tells `turbo` that this pipeline task depends on the value of that environment variable.
 
-**Example: Basics**
+<Callout type="info">
+  Using `$` to declare environment variables in the `dependsOn` config is deprecated. Use the
+  `env` key instead.
+</Callout>
+
+**Example**
 
 ```jsonc
 {
@@ -99,29 +104,31 @@ Prefixing an item in `dependsOn` with a `$` tells `turbo` that this pipeline tas
 }
 ```
 
-**Example: Environment Variables and Tasks**
+### `env`
+
+`type: string[]`
+
+The list of environment variables a task depends on.
+
+**Example**
 
 ```jsonc
 {
   "$schema": "https://turborepo.org/schema.json",
   "pipeline": {
     "build": {
-      "dependsOn": [
-        "^build",
-        "$SOMETHING_ELSE" // value will impact the hashes of all build tasks
-      ],
+      "dependsOn": ["^build"],
+      "env": ["SOMETHING_ELSE"], // value will impact the hashes of all build tasks
       "outputs": ["dist/**", ".next/**"]
     },
     "web#build": {
-      "dependsOn": [
-        "^build",
-        "$STRIPE_SECRET_KEY", // value will impact hash of only web's build task
-      ],
+      "dependsOn": ["^build"],
+      "env": ["STRIPE_SECRET_KEY"], // value will impact hash of only web's build task
       "outputs": [".next/**"]
     }
   },
-  "globalDependencies": [
-    "$GITHUB_TOKEN"// value will impact the hashes of all tasks
+  "globalEnv": [
+    "GITHUB_TOKEN"// value will impact the hashes of all tasks
   ]
 }
 ```

examples/with-docker/turbo.json

@@ -3,7 +3,8 @@
   "pipeline": {
     "build": {
       "outputs": ["dist/**", ".next/**", "public/dist/**"],
-      "dependsOn": ["^build", "$NEXT_PUBLIC_API_HOST"]
+      "dependsOn": ["^build"],
+      "env": ["NEXT_PUBLIC_API_HOST"]
     },
     "test": {
       "outputs": ["coverage/**"],