GitLab CI

Purpose and Scope

Use this guide when you want a GitLab pipeline to install a JavaScript workspace, run Turborepo tasks, and optionally share task artifacts through Remote Caching. The first-party GitLab recipe is intentionally small: it assumes the repository already has root scripts that call Turborepo, a task graph in the root configuration, and a GitLab pipeline file at the repository root. The practical goal is to make GitLab execute the same build and test commands that developers run locally while letting Turborepo decide package ordering, dependency-aware execution, and cache reuse.

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

The GitLab page is part of the broader Continuous Integration guide set. That overview frames CI setup as four repeatable actions: configure the remote-cache environment variables, clone the repository, install dependencies through the chosen package manager, and run tasks through Turborepo. GitLab supplies the vendor-specific container and cache syntax, while Turborepo keeps the task behavior portable across GitLab, GitHub Actions, CircleCI, Buildkite, Vercel, and other providers. Treat the pipeline file as orchestration around the same workspace contract rather than a second build system.

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

Relevant Source Files

• apps/docs/content/docs/guides/ci-vendors/gitlab-ci.mdx - Primary GitLab CI integration guide, including root script assumptions, task configuration, package-manager pipeline examples, and Remote Caching setup.
• apps/docs/content/docs/guides/ci-vendors/index.mdx - CI overview that defines the shared provider setup sequence and the required remote-cache variables.
• apps/docs/content/docs/guides/ci-vendors/github-actions.mdx - Neighbor provider recipe showing the same build and test scripts, plus comparable remote-cache environment variable placement.
• apps/docs/content/docs/guides/ci-vendors/circleci.mdx - Neighbor provider recipe that reinforces the shared package-manager tabs and remote-cache pattern while documenting a provider-specific terminal UI workaround.
• apps/docs/content/docs/guides/ci-vendors/buildkite.mdx - Neighbor provider recipe that shows the same package-manager task commands split into pipeline steps and describes secret handling for remote cache credentials.
• apps/docs/content/docs/guides/ci-vendors/vercel.mdx - Provider guide that describes Vercel’s zero-configuration Turborepo behavior and Vercel Remote Cache integration, which the GitLab page uses as its remote cache example.

Baseline Repository Contract

Before writing GitLab YAML, make the repository root expose task scripts that CI can call. The GitLab recipe starts with a root package manifest where build and test scripts delegate to Turborepo. That indirection matters because GitLab does not need to know every package in the monorepo. It calls the root package manager command, the package manager calls the root script, and Turborepo expands that script into package-level work according to the task graph. This keeps the pipeline stable as packages are added, removed, or reorganized.

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

{
  "name": "my-turborepo",
  "scripts": {
    "build": "turbo run build",
    "test": "turbo run test"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

The accompanying root configuration defines what those commands mean. In the GitLab example, build declares an output directory and depends on upstream builds with the caret dependency syntax, while test depends on upstream builds without declaring outputs. This is a compact but important distinction: build produces files that can be cached and restored, and test depends on the compiled state of dependencies. CI then runs build before test, but Turborepo still determines package-level ordering and cache eligibility inside each command.

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

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "outputs": [".svelte-kit/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"]
    }
  }
}

GitLab Pipeline Flow

Create the GitLab pipeline file at the repository root and choose the tab that matches the workspace package manager. The documented examples all use a single build stage and then run installation, build, and test commands within that stage. For package managers with a dependency cache, the cache is configured in GitLab YAML rather than in Turborepo. That cache reduces package installation time, while Turborepo’s own cache handles task outputs. Keeping those two cache layers separate makes failures easier to debug because dependency restoration and task artifact restoration have different inputs.

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

image: node:latest
stages:
  - build
build:
  stage: build
  before_script:
    - curl -f https://get.pnpm.io/v6.16.js | node - add --global pnpm@6.32.2
    - pnpm config set store-dir .pnpm-store
  script:
    - pnpm install
    - pnpm build
    - pnpm test
  cache:
    key:
      files:
        - pnpm-lock.yaml
    paths:
      - .pnpm-store

For pnpm, the guide installs a specific pnpm release before dependency installation and points pnpm at a repository-local store. The GitLab cache key is based on the lockfile, so a dependency graph change naturally invalidates the stored package manager data. Yarn uses the same Node image but caches package-manager directories such as the dependency folder and Yarn metadata. The npm example is the simplest, calling install, build, and test without a cache stanza in the snippet. The Bun example uses the Bun container image and places install work in a default before step.

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

Remote Caching and Secrets

Remote Caching is optional for correctness but central to making CI fast across jobs, branches, and machines. The CI overview says providers should expose two Turborepo environment variables: a bearer token and the account or team identifier associated with the repository. The GitLab guide uses Vercel Remote Cache as the concrete provider. In that flow, create a scoped access token in the Vercel dashboard, store it as a GitLab CI/CD variable named for the Turborepo token, and add a second variable containing the Vercel team slug.

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

Store these values in GitLab repository settings under the CI/CD variables area rather than committing them. Once present, the same root commands continue to work; Turborepo reads the environment and can upload or restore cache artifacts as part of task execution. This is why the pipeline examples do not add separate upload and download commands. The package manager cache remains configured in GitLab YAML, while Remote Caching is activated by Turborepo credentials in the job environment.

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

System-to-Code Mapping

The repository maps CI concerns into documentation files rather than provider-specific runtime code. The GitLab guide owns the exact file name and YAML structure for GitLab. The CI overview owns the provider-independent remote-cache setup model. Neighbor pages demonstrate that the same root package manifest and task graph appear across providers, with only orchestration syntax changing. GitHub Actions uses workflow steps and setup actions, CircleCI uses orbs and documents a terminal UI workaround, Buildkite uses pipeline steps, and Vercel documents an even higher-level deployment integration with zero-configuration remote caching.

Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, 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/vercel.mdx, apps/docs/content/docs/guides/ci-vendors/index.mdx

This mapping is useful when adapting the GitLab file to a real repository. If the root package scripts are renamed, change the GitLab script commands but keep the Turborepo delegation. If a framework writes build output somewhere other than the example directory, update the task outputs so cache hits restore the right files. If the package manager changes, switch the install command, lockfile, cache paths, and container image together. The task graph stays in the Turborepo configuration, not scattered through CI stages.

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

Testing Signals and Operational Checks

A healthy GitLab setup should show three layers completing in order: dependency installation, Turborepo build execution, and Turborepo test execution. On the first run after enabling Remote Caching, tasks may execute because no artifacts exist yet. Later runs can restore work when inputs and environment allow a cache hit. If builds run unexpectedly, inspect task outputs and environment variables before changing GitLab YAML. If installation remains slow, inspect the GitLab package-manager cache key and paths, because that concern is separate from Turborepo task artifacts.

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

Next Steps

After the basic pipeline is passing, read the CI vendor overview for the provider-neutral remote-cache checklist, then compare the GitHub Actions, CircleCI, and Buildkite pages if your organization uses multiple CI systems. For deployment-oriented workflows, review the Vercel guide because it describes the zero-configuration Turborepo integration and Vercel Remote Cache that the GitLab recipe references. For deeper tuning, continue with the Turborepo reference pages for task configuration, run options, environment variables, and Remote Caching behavior so the pipeline and task graph evolve together.

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/circleci.mdx, apps/docs/content/docs/guides/ci-vendors/buildkite.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx