CI Vendor Guides

Purpose and Scope

Use this page when you already know which tasks your repository should run in CI, but need to translate that plan into a vendor workflow. The CI vendor guide is an overview and routing page: it explains the common Turborepo setup that applies to every provider, then points teams to concrete recipes for Vercel, GitHub Actions, CircleCI, GitLab CI, and Buildkite. The shared goal is to make build and test pipelines faster by running Turborepo tasks and, when available, sharing task artifacts through Remote Caching rather than rebuilding unchanged work on every job.

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

The first design principle is vendor neutrality. The overview does not require a specific runner, cache primitive, or dashboard; it requires that the pipeline can check out the repository, install dependencies with the workspace package manager, provide Turborepo Remote Cache credentials as environment variables, and execute package scripts that call Turborepo. Provider-specific pages then adapt that neutral sequence to each platform’s syntax. This separation lets a team keep the same root scripts and Turborepo configuration while changing only workflow files, job names, package-manager setup, and secret-management mechanics.

Sources: apps/docs/content/docs/guides/ci-vendors/index.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/guides/ci-vendors/buildkite.mdx, apps/docs/content/docs/guides/ci-vendors/circleci.mdx, apps/docs/content/docs/guides/ci-vendors/gitlab-ci.mdx

Relevant Source Files

apps/docs/content/docs/guides/ci-vendors/index.mdx — overview page that defines the CI vendor section, lists provider recipes, and gives the common Remote Caching setup.
apps/docs/content/docs/guides/ci-vendors/vercel.mdx — Vercel integration page describing zero-configuration deployment and automatic use of Vercel Remote Cache.
apps/docs/content/docs/guides/ci-vendors/github-actions.mdx — GitHub Actions recipe with root scripts, task configuration, checkout, Node setup, package-manager cache, and build/test jobs.
apps/docs/content/docs/guides/ci-vendors/buildkite.mdx — Buildkite recipe with pipeline file examples, dashboard pipeline creation, and Remote Caching environment variables.
apps/docs/content/docs/guides/ci-vendors/circleci.mdx — CircleCI recipe with package-manager examples and the required terminal UI workaround for CircleCI TTY behavior.
apps/docs/content/docs/guides/ci-vendors/gitlab-ci.mdx — GitLab CI recipe with package-manager-specific pipeline examples, dependency cache examples, and Remote Cache variable setup.

Core CI Primitives

Every provider recipe assumes a small set of stable primitives. The repository root exposes scripts such as build and test that delegate to Turborepo task execution, commonly by running a build task and a test task. The Turborepo configuration defines those tasks, their upstream dependency ordering, and their cacheable outputs. Provider workflows should call the package-manager script rather than duplicating per-package commands, because Turborepo then decides which package tasks need to execute, which can be restored, and which depend on upstream package builds.

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

Remote Caching is the other shared primitive. The overview instructs CI systems to set two environment variables before running tasks: the bearer token used to access the remote cache and the account or team name associated with the repository. When using Vercel Remote Cache, the team value is the team slug. These variables are not task inputs for an application build; they configure Turborepo’s own cache access in the runner. Once the variables are present, the remaining steps are the familiar CI sequence: clone, install dependencies, and run tasks through Turborepo.

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

General Setup Flow

Start with the repository contract rather than the vendor UI. Add root scripts for the tasks that CI should run, such as a build script that runs the build task and a test script that runs the test task. Define the task graph so builds can depend on upstream package builds and so output directories are declared accurately. The examples use build outputs such as framework build folders while excluding development or framework-internal caches where appropriate. This matters because incorrect outputs can either miss reusable artifacts or store files that should not be restored in later CI jobs.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/guides/ci-vendors/buildkite.mdx, apps/docs/content/docs/guides/ci-vendors/circleci.mdx, apps/docs/content/docs/guides/ci-vendors/gitlab-ci.mdx

After the repository contract is in place, create the vendor workflow file in the location expected by that provider. GitHub Actions uses a workflow file under the GitHub workflows directory and demonstrates checkout with a small fetch depth, Node setup, package-manager caching, dependency installation, then separate build and test steps. Buildkite uses a pipeline file with labeled test and build steps and also documents uploading the repository pipeline definition from the Buildkite dashboard. GitLab CI uses a root CI file with stages, scripts, and package-manager cache settings. CircleCI uses a configuration file with a Node orb, checkout, install, build, and test steps.

./package.json

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

./turbo.json

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

Provider-Specific Notes

Vercel is the simplest provider path in the supplied recipes. The Vercel page states that the integration automatically understands a Turborepo monorepo and that importing the code into a new Vercel project preconfigures projects to use the Vercel Remote Cache. Treat this as the zero-configuration deployment route when your applications are hosted on Vercel. In contrast, the other provider pages are workflow recipes: they show how to wire package-manager installation, task execution, dependency caches, and Remote Cache credentials into each provider’s own configuration language.

Sources: apps/docs/content/docs/guides/ci-vendors/vercel.mdx, apps/docs/content/docs/guides/ci-vendors/index.mdx

CircleCI has a notable operational edge case. The CircleCI guide warns that CircleCI uses interactive terminals that can crash Turborepo’s terminal UI, so its examples set the Turborepo UI environment variable to false around install or task execution steps. This is not a general requirement for every provider; it is a CircleCI-specific workaround. Buildkite has a different provider-specific concern: before normal builds run, the dashboard pipeline must be created and include a step that uploads the pipeline definition from the repository. GitLab CI examples emphasize package-manager cache paths such as pnpm store, Yarn directories, or Bun lockfile-based caches.

Sources: apps/docs/content/docs/guides/ci-vendors/circleci.mdx, apps/docs/content/docs/guides/ci-vendors/buildkite.mdx, apps/docs/content/docs/guides/ci-vendors/gitlab-ci.mdx

Remote Cache Configuration Reference

Name	Where it is set	Purpose
TURBO_TOKEN	CI secret or provider variable	Bearer token used by Turborepo to access the Remote Cache.
TURBO_TEAM	CI variable or secret, depending on provider	Account name or Vercel team slug associated with the repository and shared artifacts.
TURBO_UI	CircleCI job environment	Set to false in CircleCI examples to avoid terminal UI crashes caused by interactive TTY behavior.

The Remote Cache setup should be handled as provider configuration, not committed application configuration. GitLab CI documents adding the token and team values through repository CI/CD variables, while Buildkite documents creating Buildkite secrets for the two values. GitHub Actions examples show the values as commented environment entries that would read from secrets and variables. This difference is only about secret storage. The values have the same meaning across providers, and once they are exposed to the job environment, the task command remains the normal build or test script.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/guides/ci-vendors/buildkite.mdx, apps/docs/content/docs/guides/ci-vendors/gitlab-ci.mdx, apps/docs/content/docs/guides/ci-vendors/circleci.mdx

Choosing the Next Recipe

Choose the provider page that matches where the pipeline will run, then copy the example closest to your package manager. Use the GitHub Actions recipe when you need branch and pull request triggers with Node setup and package-manager caching. Use the Buildkite recipe when your organization manages pipelines from the Buildkite dashboard and wants separate labeled steps. Use the CircleCI recipe when you need CircleCI’s Node orb and remember the UI workaround. Use the GitLab CI recipe when your repository runs stages from GitLab and wants the cache configuration expressed directly in the CI file. Use the Vercel page when deployment and Remote Cache integration are handled by Vercel’s monorepo support.

Sources: apps/docs/content/docs/guides/ci-vendors/index.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx, apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/guides/ci-vendors/buildkite.mdx, apps/docs/content/docs/guides/ci-vendors/circleci.mdx, apps/docs/content/docs/guides/ci-vendors/gitlab-ci.mdx

Ask a question...