1# Environment Variables in Turborepo
2 
3Turborepo provides fine-grained control over which environment variables affect task hashing and runtime availability.
4 
5## Configuration Keys
6 
7### `env` - Task-Specific Variables
8 
9Variables that affect a specific task's hash. When these change, only that task rebuilds.
10 
11```json
12{
13  "tasks": {
14    "build": {
15      "env": ["DATABASE_URL", "API_KEY"]
16    }
17  }
18}
19```
20 
21### `globalEnv` - Variables Affecting All Tasks
22 
23Variables that affect EVERY task's hash. When these change, all tasks rebuild.
24 
25```json
26{
27  "globalEnv": ["CI", "NODE_ENV"]
28}
29```
30 
31### `passThroughEnv` - Runtime-Only Variables (Not Hashed)
32 
33Variables available at runtime but NOT included in hash. **Use with caution** - changes won't trigger rebuilds.
34 
35```json
36{
37  "tasks": {
38    "deploy": {
39      "passThroughEnv": ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
40    }
41  }
42}
43```
44 
45### `globalPassThroughEnv` - Global Runtime Variables
46 
47Same as `passThroughEnv` but for all tasks.
48 
49```json
50{
51  "globalPassThroughEnv": ["GITHUB_TOKEN"]
52}
53```
54 
55## Wildcards and Negation
56 
57### Wildcards
58 
59Match multiple variables with `*`:
60 
61```json
62{
63  "env": ["MY_API_*", "FEATURE_FLAG_*"]
64}
65```
66 
67This matches `MY_API_URL`, `MY_API_KEY`, `FEATURE_FLAG_DARK_MODE`, etc.
68 
69### Negation
70 
71Exclude variables (useful with framework inference):
72 
73```json
74{
75  "env": ["!NEXT_PUBLIC_ANALYTICS_ID"]
76}
77```
78 
79## With `futureFlags.globalConfiguration`
80 
81When the `globalConfiguration` future flag is enabled, global environment keys move under the `global` key with cleaner names:
82 
83| Old (top-level)        | New (`global.`)  |
84| ---------------------- | ---------------- |
85| `globalEnv`            | `env`            |
86| `globalPassThroughEnv` | `passThroughEnv` |
87 
88`global.env` and `global.passThroughEnv` behave identically to their top-level counterparts — they affect the global hash and all tasks, respectively. The rename is purely organizational.
89 
90```json
91{
92  "futureFlags": { "globalConfiguration": true },
93  "global": {
94    "env": ["CI", "NODE_ENV"],
95    "passThroughEnv": ["GITHUB_TOKEN", "NPM_TOKEN"]
96  },
97  "tasks": {
98    "build": {
99      "env": ["DATABASE_URL", "API_*"],
100      "passThroughEnv": ["SENTRY_AUTH_TOKEN"]
101    }
102  }
103}
104```
105 
106## Complete Example
107 
108```json
109{
110  "$schema": "https://v2-9-12.turborepo.dev/schema.json",
111  "globalEnv": ["CI", "NODE_ENV"],
112  "globalPassThroughEnv": ["GITHUB_TOKEN", "NPM_TOKEN"],
113  "tasks": {
114    "build": {
115      "env": ["DATABASE_URL", "API_*"],
116      "passThroughEnv": ["SENTRY_AUTH_TOKEN"]
117    },
118    "test": {
119      "env": ["TEST_DATABASE_URL"]
120    }
121  }
122}
123```
124