1# CI/CD with Turborepo
2 
3General principles for running Turborepo in continuous integration environments.
4 
5## Core Principles
6 
7### Always Use `turbo run` in CI
8 
9**Never use the `turbo <tasks>` shorthand in CI or scripts.** Always use `turbo run`:
10 
11```bash
12# CORRECT - Always use in CI, package.json, scripts
13turbo run build test lint
14 
15# WRONG - Shorthand is only for one-off terminal commands
16turbo build test lint
17```
18 
19The 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`.
20 
21### Enable Remote Caching
22 
23Remote caching dramatically speeds up CI by sharing cached artifacts across runs.
24 
25Required environment variables:
26 
27```bash
28TURBO_TOKEN=your_vercel_token
29TURBO_TEAM=your_team_slug
30```
31 
32### Use --affected for PR Builds
33 
34The `--affected` flag only runs tasks for packages changed since the base branch:
35 
36```bash
37turbo run build test --affected
38```
39 
40This requires Git history to compute what changed.
41 
42## Git History Requirements
43 
44### Fetch Depth
45 
46`--affected` needs access to the merge base. Shallow clones break this.
47 
48```yaml
49# GitHub Actions
50- uses: actions/checkout@v4
51  with:
52    fetch-depth: 2 # Minimum for --affected
53    # Use 0 for full history if merge base is far
54```
55 
56### Why Shallow Clones Break --affected
57 
58Turborepo compares the current HEAD to the merge base with `main`. If that commit isn't fetched, `--affected` falls back to running everything.
59 
60For PRs with many commits, consider:
61 
62```yaml
63fetch-depth: 0 # Full history
64```
65 
66## Environment Variables Reference
67 
68| Variable            | Purpose                              |
69| ------------------- | ------------------------------------ |
70| `TURBO_TOKEN`       | Vercel access token for remote cache |
71| `TURBO_TEAM`        | Your Vercel team slug                |
72| `TURBO_REMOTE_ONLY` | Skip local cache, use remote only    |
73| `TURBO_LOG_ORDER`   | Set to `grouped` for cleaner CI logs |
74 
75## See Also
76 
77- [github-actions.md](./github-actions.md) - GitHub Actions setup
78- [vercel.md](./vercel.md) - Vercel deployment
79- [patterns.md](./patterns.md) - CI optimization patterns
80