Constructing CI

Purpose and Scope

Continuous Integration is where Turborepo’s task model becomes most valuable: the pipeline can build, lint, test, and deploy only the work that matters while reusing prior results from cache. The first-party CI guide frames Turborepo as a way to accelerate required CI tasks through parallelization and Remote Caching, and it points teams toward vendor-specific recipes when they need exact setup syntax. This page explains the vendor-neutral design: define reliable tasks, make outputs cacheable, enable remote cache credentials, and use filters or affected detection to reduce unnecessary work.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx

A Turborepo CI pipeline should be treated as the same workflow developers run locally, not a separate build system. The constructing-ci guide recommends installing turbo globally on development and CI machines so one mental model can operate the whole repository, while also noting that tasks registered in turbo.json work the same way in CI. That consistency matters because failures and cache misses become easier to reason about: the pipeline runs named tasks such as build and test, and Turborepo decides ordering, parallelism, and cache restoration from the repository configuration.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

Relevant Source Files

• apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx - Primary guide for CI setup, Remote Caching environment variables, task execution in CI, filtering, affected work, and Docker-oriented deployment notes.
• apps/docs/content/docs/guides/ci-vendors/github-actions.mdx - Concrete GitHub Actions workflow examples showing checkout depth, package manager setup, Node caching, install steps, and pnpm build or equivalent task execution.
• apps/docs/content/docs/guides/ci-vendors/vercel.mdx - Vercel integration guidance describing zero-config monorepo understanding and automatic Vercel Remote Cache configuration.
• apps/docs/content/docs/crafting-your-repository/caching.mdx - Background for local and remote caching, task fingerprints, deterministic task assumptions, cache hits, and .turbo/cache behavior.
• apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx - Task configuration guide for turbo.json, tasks, dependsOn, outputs, and the turbo run execution model.
• apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx - Internal package workflow that explains how workspace dependencies produce a package graph Turborepo can optimize in CI.

CI Pipeline Building Blocks

A minimal CI design starts with package manager scripts that delegate to Turborepo. The GitHub Actions guide uses a root package.json with build mapped to turbo run build and test mapped to turbo run test, with turbo in devDependencies. This keeps vendor configuration small: the CI job installs dependencies, then calls the same package scripts a developer would use. The important boundary is that package managers install and invoke commands, while Turborepo orchestrates package tasks across the workspace.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

{
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

The next building block is turbo.json. The task configuration guide defines a task as a script Turborepo runs, and explains that each key in the tasks object can be executed by turbo run when matching package scripts exist. CI should not rely on accidental script ordering. Instead, encode build order and cacheable outputs. For example, dependsOn: ["^build"] tells Turborepo to build dependencies before dependents, and outputs tells Turborepo which generated files can be restored from cache.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**", "other-output-dirs/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"]
    }
  }
}

Internal packages are the reason dependency-aware CI works across a monorepo. The internal package guide explains that Turborepo reads relationships from package.json dependencies and creates a Package Graph under the hood. In practice, if an app depends on a shared package such as @repo/math, the graph lets ^build place the package build before the app build. CI does not need to manually enumerate that order. It should keep workspace package manifests accurate and let Turborepo use those dependency edges.

Sources: apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

Remote Caching in CI

Remote Caching is the most important CI acceleration step after task configuration. The CI guide states that CI needs environment variables that allow Turborepo to access the Remote Cache: TURBO_TOKEN for the bearer token and TURBO_TEAM for the account name associated with the repository. With those values present, task runs through turbo can hit cache instead of repeating work. The Vercel CI/CD integration is called out separately because it is automatically connected to managed Vercel Remote Cache with zero configuration.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx

Caching only works predictably when tasks are deterministic from Turborepo’s point of view. The caching guide explains that Turborepo restores results from cache using a fingerprint from the first time the task ran, and warns that if a task can produce different outputs for the same known inputs, caching may not work as expected. CI pipeline authors should therefore include relevant source files, configuration, and environment dependencies in task inputs and environment handling, then declare generated outputs accurately so restored artifacts match what the deploy or test step expects.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

Running Only the Work That Matters

Once the repository has reliable tasks and cache credentials, reduce the number of task invocations. The CI guide recommends the same --filter flag used locally, including filtering by packages, directories, and Git history. This is useful for entry-point pipelines such as deploying one app or validating a changed package subset. The guide also points to --affected for running tasks only in packages that have changes. The critical CI constraint is source history: Git-history filtering requires history to be available on the machine, so shallow clones can prevent those queries from working as intended.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

A vendor-neutral flow is therefore: check out enough Git history, install dependencies using the repository’s package manager, expose remote cache credentials, and call a package script that delegates to turbo run. GitHub Actions examples use actions/checkout@v4 with fetch-depth: 2, set up Node 20, enable package-manager dependency caching through actions/setup-node@v4, install dependencies, then run build and test scripts. Other CI systems can follow the same sequence even when their YAML syntax differs.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

steps:
  - name: Check out code
    uses: actions/checkout@v4
    with:
      fetch-depth: 2
  - name: Setup Node.js environment
    uses: actions/setup-node@v4
    with:
      node-version: 20
      cache: 'pnpm'
  - name: Install dependencies
    run: pnpm install
  - name: Build
    run: pnpm build
  - name: Test
    run: pnpm test

Docker and Deployment Pipelines

Many CI pipelines end by building a deployable container or publishing an application artifact. The CI guide explicitly calls Docker an important part of many deployment pipelines and points to Turborepo’s prune subcommand for lightweight Docker workflows. The main design principle is to avoid sending the whole monorepo into a deployment build when only one entry point is needed. Use task filters to validate the relevant app and its dependencies, then use pruning-oriented workflows for packaging so dependency installation and image layers stay focused on the deploy target.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Vercel is a special deployment target because the Vercel guide says its integration automatically understands Turborepo monorepos and pre-configures projects to use Vercel Remote Cache when code is imported. For teams deploying elsewhere, the same concepts still apply manually: provide TURBO_TOKEN and TURBO_TEAM, preserve enough Git history for affected checks, run repository scripts backed by turbo run, and keep turbo.json task outputs aligned with what the deploy step consumes. The difference is not Turborepo’s model, but how much CI vendor configuration you must write.

Sources: apps/docs/content/docs/guides/ci-vendors/vercel.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Implementation Checklist

Use this checklist when turning a local Turborepo workspace into CI. First, create or audit root scripts such as build and test so they call turbo run build and turbo run test. Second, ensure turbo.json declares task dependencies with dependsOn, especially ^build when applications consume internal packages. Third, declare outputs for cacheable tasks, excluding tool-specific transient directories such as framework dev caches where appropriate. Fourth, configure TURBO_TOKEN and TURBO_TEAM in CI secrets or variables unless the provider supplies Remote Cache automatically.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Finally, add selection logic only after the full pipeline is correct. Start by running the same tasks everywhere, observe cache behavior, then introduce --filter or --affected to narrow work for pull requests, deploy jobs, or package-specific checks. If affected queries behave unexpectedly, confirm that the checkout step provides usable history. If cache hits are missing, inspect task determinism, inputs, outputs, and environment variables before assuming the CI vendor is at fault. Next, read the CI vendor guides for exact YAML and the caching, configuration, and query references for deeper tuning.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx