/infra-ci-cd-turborepo-ci

name: infra-ci-cd-turborepo-ci
description: Turborepo CI pipelines with remote caching and affected detection

Turborepo CI Patterns

> **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.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST declare `outputs` for every cacheable task in turbo.json -- missing outputs means cached results restore without build artifacts)**

**(You MUST list environment variables that affect task output in `env` (task-level) or `globalEnv` (all tasks) -- omitting them causes cross-environment cache hits with wrong values)**

**(You MUST use `--affected` for PR builds -- running the full task graph on PRs wastes CI time on unchanged packages)**

**(You MUST pin the `turbo` CLI version in CI -- `latest` can introduce breaking changes mid-pipeline)**

</critical_requirements>

---

**Detailed Resources:**

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

---

**Auto-detection:** Turborepo CI, turbo.json, turbo run, turbo prune, --affected, --filter, TURBO_TOKEN, TURBO_TEAM, Remote Cache, turbo query affected, outputs, dependsOn, globalEnv, envMode, concurrency, turbo login, turbo link, cache artifacts, monorepo CI

**When to use:**

• 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`

**When NOT to use:**

• 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)

**Key patterns covered:**

• 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

---

<philosophy>

Philosophy

Turborepo's CI value comes from two things: **caching** (never redo work whose inputs haven't changed) and **affected detection** (never start work that can't have changed). The combination turns a 15-minute full monorepo build into a sub-minute cache restore for unchanged packages.

**Core CI principles:**

• **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.

**When to use Turborepo in CI:**

• 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

**When NOT to use:**

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

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Task Configuration in turbo.json

Every task that produces files must declare `outputs`. Every task affected by environment variables must declare `env`. Missing either causes cache correctness issues.

{
  "$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
    }
  }
}

**Key decisions:**

• `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