CI/CD with Turborepo

General principles for running Turborepo in continuous integration environments.

Core Principles

Always Use turbo run in CI

Never use the turbo <tasks> shorthand in CI or scripts. Always use turbo run:

# CORRECT - Always use in CI, package.json, scripts
turbo run build test lint

# WRONG - Shorthand is only for one-off terminal commands
turbo build test lint

The shorthand turbo <tasks> is only for one-off invocations typed directly in terminal by humans or agents. Anywhere the command is written into code (CI, package.json, scripts), use turbo run.

Enable Remote Caching

Remote caching dramatically speeds up CI by sharing cached artifacts across runs.

Required environment variables:

TURBO_TOKEN=your_vercel_token
TURBO_TEAM=your_team_slug

Use --affected for PR Builds

The --affected flag only runs tasks for packages changed since the base branch:

turbo run build test --affected

This requires Git history to compute what changed.

Git History Requirements

Fetch Depth

--affected needs access to the merge base. Shallow clones break this.

# GitHub Actions
- uses: actions/checkout@v4
  with:
    fetch-depth: 2 # Minimum for --affected
    # Use 0 for full history if merge base is far

Why Shallow Clones Break --affected

Turborepo compares the current HEAD to the merge base with main. If that commit isn't fetched, --affected falls back to running everything.

For PRs with many commits, consider:

fetch-depth: 0 # Full history

Environment Variables Reference

See Also

• github-actions.md - GitHub Actions setup
• vercel.md - Vercel deployment
• patterns.md - CI optimization patterns