Hey, @bitttttten, I can see how this can be confusing. I’ll shed some light.

Turborepo has to account for environment variables that come from the operating system and ones that come from files differently. I’m realizing our documentation needs to be more clear about this. I’ll update that.

In the meantime, the specific reasoning behind the behavior you’re seeing is:

• passThroughEnv is for passing through environment variables that come from the operating system. Because vc env pull creates a file, passThroughEnv won’t be on the path between the .env file and Turborepo’s hashing. The passThroughEnv configuration you’re showing ends up not affecting this situation.
• The apps/web/.env file is likely changing in between test runs, since VERCEL_OIDC_TOKEN is short-lived. When that file changes, the hash changes, resulting in a cache miss.

The question that leaves me with is: Why is that file included in your hashes?

• Turborepo’s hashing ignores .gitignore’d files by default. Is .env ignored in your gitignore?
• Is there anywhere that this file is being added to the hash? Something like .env or **/.env*in a turbo.json?
• Another way that these can sneak by is if you use the inputs key on a task, but you’re showing a task that doesn’t have one, so I’ll rule that out.

To summarize:

• passThroughEnv doesn’t affect this behavior.
• The contents of the apps/web/.env file is indeed changing, since VERCEL_OIDC_TOKEN is changing.
• It’s hard to tell why the .env file is included in your hashing without more detail.

If you can reason about those pieces with your repo, you’ll be able to get cache hits for that task.

The question that leaves me with is: Why is that file included in your hashes?

Right! Well we have this in our turbo config:

1{2  "$schema": "https://turbo.build/schema.json",3  "globalDependencies": ["**/.env", ".env"],4  "tasks": {5    "build": {6      "dependsOn": ["^build"],7      "outputs": ["dist/**", ".next/**"],8      "env": [9        "TURBO_TEAM",10        "TURBO_PREFLIGHT",11        "TURBO_TOKEN",12        "TURBO_API",13        // ..14        "NODE_ENV",15        "VITE_*",16        "NEXT_PUBLIC_*",17        "VERCEL_*",18        "VERCEL",19        "OTEL_SERVICE_NAME",20        "OTEL_EXPORTER_OTLP_SPAN_ENDPOINT",21        "OTEL_EXPORTER_OTLP_SPAN_TOKEN",22        /// 23      ],24      "passThroughEnv": ["VERCEL_OIDC_TOKEN"]25    },26  }27}28

So someone has added "globalDependencies": ["**/.env", ".env"], 🤔

If I am understanding your message, you’re saying that this shouldn’t necessarily be in there?

In that case, Turborepo is exhibiting the expected behavior. 👍

As you’re seeing globalDependencies is a big hammer. Any changes to the contents of any of those files will cause cache misses. What I frequently see as what folks want is for build to miss cache on changes to .env files, but everything else can hit cache. That would look like:

1{2  "tasks": {3    "build": {4      "inputs": ["$TURBO_DEFAULT", "$TURBO_ROOT$/.env", ".env*"]5    }6  }7}

Docs for $TURBO_DEFAULT: https://turborepo.com/docs/reference/configuration#turbo_default Docs for $TURBO_ROOT: https://turborepo.com/docs/reference/configuration#turbo_root

This would mean that .env* is meaning for your build task, but not meaningful for all of your other tasks. that’s usually what people are looking for. If that’s not what you’re looking for then, hopefully that can at least help you construct the behavior you’re looking for.

Wow thanks so much! This is super helpful. Indeed I think the intention is only to do this for builds.

So for example, if someone sets “tasks.build.env”, this is just environment variables from the shell for example. Having the .env as an task.build.inputs, means it’s the whole contents. So what I mean is sometimes I see things inside the “env” array. This would also be unnecessary then right?

i.e.

{ "$schema": "``https://turbo.build/schema.json", "ui": "tui", "tasks": { "build": { "dependsOn": ["^build"], "outputs": [".next/**"], “inputs”: ["$TURBO_DEFAULT", "$TURBO_ROOT$/.env", ".env*"], "env": [ “SOME_ENV_VAR” ], } } }

So if SOME_ENV_VAR was only ever set inside the .env file, and never “exported”, then this would also be unnecessary right? Basically “env” is taking shell environment variables, it’s not diving into .env file (unless you mainly export all vars from inside the .env file before running build). Is that also correct to say?

Thanks for the links to the docs, really helps!

Yes, env only applies to system environment variables coming directly from the OS.