Quick Guide: Use

--affected

for PR builds (auto-detects CI environment, falls back to full suite on shallow clones). Enable Remote Cache with

TURBO_TOKEN

+

TURBO_TEAM

env vars. Declare

outputs

for every cacheable task or cached results will be incomplete. Use

env

and

globalEnv

in turbo.json to include environment variables in cache hashes -- missing entries cause cross-environment cache collisions. Pin

turbo

version in CI. Use

turbo query affected

to conditionally skip entire CI steps.

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

outputs

env

globalEnv

--affected

turbo

latest

• examples/core.md - turbo.json task config, outputs, env, caching control, filter syntax
• examples/remote-cache.md - Remote Cache setup, self-hosted options, signature verification
• examples/affected-detection.md - --affected flag, turbo query affected, conditional CI steps
• examples/docker.md - turbo prune --docker, multi-stage Dockerfile, layer caching
• reference.md - Decision frameworks, CLI flags, turbo.json quick reference

• Configuring CI pipelines for a Turborepo monorepo
• Setting up Remote Cache for shared build artifacts across CI and local
• Using

  --affected

  to run only changed-package tasks on PRs
• Optimizing Docker builds with

  turbo prune --docker

• Debugging cache misses with

  --summarize

  or

  --dry

• Skipping CI steps conditionally with

  turbo query affected

• General Turborepo workspace setup (package structure, task graph design) -- that belongs in a monorepo/workspace skill
• CI provider-specific workflow syntax (use your CI provider's skill)
• Application build configuration (bundler, compiler settings)

• turbo.json task configuration (

  outputs

  ,

  env

  ,

  dependsOn

  ,

  cache

  ,

  inputs

  )
• Remote Cache authentication and setup (

  TURBO_TOKEN

  ,

  TURBO_TEAM

  , signature verification)
• Affected detection (

  --affected

  ,

  --filter=...[origin/main]

  ,

  turbo query affected

  )
• Docker optimization with

  turbo prune --docker

  and multi-stage builds
• Cache debugging (

  --summarize

  ,

  --dry

  ,

  --force

  )
• Environment variable modes (

  strict

  vs

  loose

  ) and

  passThroughEnv

• Concurrency control and output log filtering

• Cache correctness over speed: A wrong cache hit is worse than a cache miss. Declare all

  outputs

  and all

  env

  variables that affect task results.
• Affected detection for PRs, full suite for main: PRs get fast feedback via

  --affected

  . Main branch runs the full task graph to catch integration issues.
• Remote Cache for team-wide sharing: Local cache is per-machine. Remote Cache shares artifacts across CI runners and developer machines, eliminating redundant work organization-wide.
• Pin versions in CI: Turborepo follows semver, but

  latest

  in CI means non-reproducible builds. Pin to the major version at minimum.

• Monorepo with 2+ packages where cross-package caching saves meaningful time
• Teams where multiple developers and CI runners rebuild the same packages
• Projects where Docker builds benefit from pruned lockfiles

• Single-package repos (no cross-package caching benefit)
• Repos where every PR touches every package (affected detection provides no speedup)

outputs

env

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "build/**"],
      "env": ["NODE_ENV", "API_URL"],
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "env": ["DATABASE_URL"],
    },
    "lint": {
      "dependsOn": [],
      "cache": true,
    },
    "type-check": {
      "dependsOn": ["^build"],
      "cache": true,
    },
  },
}

• dependsOn: ["^build"]

  means "run build in all dependencies first" -- the

  ^

  prefix means upstream packages

• outputs

  defines what gets cached and restored -- omit it and cached runs produce empty results

• env

  includes variables in the cache hash -- change the value, bust the cache

• cache: false

  disables caching for tasks like

  dev

  or deployment scripts

inputs

passThroughEnv

outputLogs

Run expensive deployment steps

See [examples/affected-detection.md](examples/affected-detection.md) for PR vs main branch patterns and `turbo query affected` examples.

---

• Declare all

  outputs

  and

  env

  variables to prevent false misses
• Use

  --summarize

  to compare hashes between runs and identify unexpected invalidations
• Keep

  globalEnv

  minimal -- variables there bust cache for ALL tasks
• Use task-level

  env

  for variables that only affect specific tasks

undefined

**Output log filtering for CI readability:**

```jsonc
{
  "tasks": {
    "build": {
      "outputLogs": "new-only",
    },
    "lint": {
      "outputLogs": "errors-only",
    },
  },
}

full

hash-only

new-only

errors-only

none

• PR build: < 3 min (with affected + Remote Cache)
• Main build: < 10 min (full suite)
• Cache hit rate: > 80% on Remote Cache
• Docker build: < 5 min with pruned lockfile

• Missing

  outputs

  on cacheable tasks -- cached runs restore nothing, tasks appear to succeed but produce no artifacts
• Missing

  env

  for environment-dependent tasks -- build with

  API_URL=staging

  hits cache from

  API_URL=production

  , serving wrong config
• Using

  latest

  turbo version in CI -- non-reproducible builds, potential breaking changes mid-pipeline
• Shallow clones without fallback --

  --filter=...[origin/main]

  fails when git history is insufficient;

  --affected

  handles this gracefully by falling back to full suite

• All environment variables in

  globalEnv

  -- every change busts cache for ALL tasks; use task-level

  env

  for task-specific variables
• No

  --affected

  on PR builds -- full task graph on PRs wastes CI time rebuilding unchanged packages
• Missing signature verification on shared Remote Cache -- unsigned artifacts can be tampered with in shared environments
• Not using

  turbo run

  explicitly in CI -- bare

  turbo build

  may conflict with future CLI subcommands

• Forgetting

  dependsOn: ["^build"]

  for tasks that consume upstream package outputs (test/lint fail because dependency not built)
• Using

  loose

  env mode and wondering why cache hits serve wrong environment config
• Not including

  globalDependencies

  for files like

  .env

  or

  tsconfig.base.json

  that affect all packages
• Setting

  cache: false

  on tasks that should be cached (e.g., test, lint) because of past debugging and forgetting to re-enable

• --affected

  auto-detects GitHub Actions via

  GITHUB_BASE_REF

  -- other CI providers may need manual

  --filter

  instead

• turbo query affected

  returns JSON -- parse with

  jq

  for conditional CI steps

• outputs

  globs are relative to the package directory, not the repo root

• $TURBO_DEFAULT$

  in

  inputs

  restores the default input behavior when you only want to add inputs, not replace them
• Remote Cache

  signature: true

  requires

  TURBO_REMOTE_CACHE_SIGNATURE_KEY

  -- missing key means cache reads fail silently (treated as misses)

• --summarize

  output goes to

  .turbo/runs/

  -- useful for diffing hashes between two runs to find what changed
• Circular package dependencies are allowed since v2.9 (validated at task graph level, not package graph level)

• --parallel

  flag is deprecated -- use

  persistent: true

  in turbo.json for long-running tasks instead

• turbo-ignore

  is deprecated -- use

  turbo query affected

  instead for conditional CI steps

• remoteCache.timeout

  default is 30s,

  uploadTimeout

  is 60s -- increase for large monorepo artifacts

All code must follow project conventions in CLAUDE.md

outputs

env

globalEnv

--affected

turbo

latest