Guide

Turbo remote build cache

Turbo shares build artifacts through a remote cache. Local machines use Vercel-hosted Turbo Remote Cache. Depot CI uses Depot Cache, which Depot runners inject automatically — do not override TURBO_API, TURBO_TEAM, or TURBO_TOKEN in .depot/workflows.

Depot workflows also cache the .turbo/ directory between runs via actions/cache as a fallback when remote cache is cold or unreachable.

Local development (Vercel)

Repository → Settings → Secrets and variables → Actions (for GitHub dual-run copies only; Depot CI does not read these for Turbo):

TypeNameValue
SecretTURBO_TOKENVercel API token (vercel.com/account/tokens), scoped to your team
VariableTURBO_TEAMYour Vercel team slug (from the team URL, e.g. your-org)

Interactive (humans)

npx turbo login
npx turbo link

Both write to ~/.turbo/config.json (per machine, not committed). After that, turbo run uses Vercel Remote Cache when available.

Non-interactive (agents, automation on a workstation)

export TURBO_TOKEN="<your-vercel-token>"
export TURBO_TEAM="<your-vercel-team-slug>"

Depot CI (Depot Cache)

Depot GitHub Actions runners (depot-ubuntu-latest) pre-configure Turborepo for Depot Cache:

  • TURBO_API — Depot cache endpoint (runner-internal proxy to cache.depot.dev)
  • TURBO_TEAM — Depot organization ID
  • TURBO_TOKEN — short-lived DEPOT_CACHE_TOKEN for the job

Do not load a Vercel TURBO_TOKEN from Platform Secrets or set vars.TURBO_TEAM on Depot Turbo jobs. Mixing Vercel credentials with Depot's TURBO_API causes 401 Unauthorized on remote cache reads/writes; builds still succeed but only hit the local .turbo/ fallback (which can serve stale artifacts).

Workflows that run Turbo on Depot today:

.depot/workflows/copy-to-wpcomvip.yml does not invoke Turbo.

Cache behavior

  • Local: .turbo/ stores task outputs keyed by hashed inputs; remote hits go to Vercel.
  • Depot CI: remote hits go to Depot Cache; actions/cache on .turbo/ is a secondary fallback keyed by package-lock.json + turbo.json.

Local Vercel cache and Depot CI cache are separate namespaces. A cache hit on your laptop does not populate Depot CI (and vice versa) until a successful remote write occurs in that environment.

Force a rebuild

npx turbo run build --force

Or clear the local cache:

rm -rf .turbo

What gets cached

See outputs in turbo.json. If a package writes outputs outside declared outputs, Turbo may warn and skip caching that task until turbo.json is updated.

Package-specific output scopes

Some workspaces declare narrower outputs than the default build task because they ship committed artifacts outside the usual build/ tree:

WorkspaceCached outputsExcluded (committed, not restored from cache)
@prc/interactive-features#buildbuild/**, includes/**/build/**assets/**/build/** — per-feature bundles under assets/{area}/{year}/{slug}/build/

@prc/interactive-features keeps hundreds of legacy feature bundles in git. A release build that restored assets/**/build/** from Turbo cache could overwrite those committed artifacts with stale or empty cache entries (#3617). Rebuild individual feature assets under assets/ with @wordpress/scripts when you change their src/ — the root build task only compiles plugin blocks and the inspector panel.

Verifying CI cache

  1. Run a Depot workflow that builds with Turbo twice with the same package-lock.json / turbo.json (e.g. deploy-to-staging.yml via workflow_dispatch).
  2. In the Build all plugins (or Build all packages) step, confirm Turbo summary lines show remote cache hits and no 401 Unauthorized / failed to contact remote cache errors.
  3. The Restore Turbo local cache (CI fallback) step may also show a hit on the second run.

build-release.yml runs on release: [published] (not workflow_dispatch); for ad hoc verification prefer staging deploy or a local npx turbo run build with Vercel credentials set.

Was this helpful?