How to correctly compose Gitlab CI with turborepo?

[inikonorov]

Summary

Hi! I'm interesting with compose Gitlab CI with Turborepo, I don't understand how to do it correctly. We don't use Turborepo cache, so in my mind there is a conflict of what Turborepo must do and what need to do in CI/CD process. Currently there are some thoughts:

• there is a turbo.json, where there are not any dependsOn options, because we use Just In Time compilation for dependencies
• we try to generate child pipelines to achieve the next flow:
  a) every app has own .gitlab-ci.yml
  b) pipeline generator read npx turbo ls --affected output and generate pipeline for every app, that changed

in this flow what is responsibility of Turborepo? okay, there is a lint command in every app which one launches lint process in app and it's dependencies, but what about other commands?

in my mind it must works the next way:

• we define all commands in turbo.json with all dependsOn settings
• and somehow do simple gitlab-ci.yml, which one just start turborepo commands

but this behavior is unreachable, because gitlab-ci.yml can't create dynamic jobs with own settings like .env files and so on, so I can't see all picture, please, help me, give me some examples of turborepo integration with Gitlab

I must keep all deps inside turbo.json and keep gitlab-ci.yml simple where I just run turborepo tasks, or I should keep turbo.json simple and describe all commands inside gitlab-ci.yml?

Additional information

No response

Example

No response

[apoorva-01]

Your second instinct is the right one: dependency graph lives in turbo.json, GitLab just runs turbo tasks. You don't need child pipelines for this, and generating one pipeline per app is actively working against turbo since each child only sees its own slice and can't dedupe shared work between apps.

Roughly:

variables:
  GIT_DEPTH: 0   # important, see below

build:
  script:
    - pnpm install --frozen-lockfile
    - pnpm turbo run lint build test --affected

--affected is what replaces your turbo ls --affected + codegen. Per the docs it's equivalent to --filter=...[main...HEAD], and there's a caveat that bites everyone on GitLab:

The comparison requires everything between base and head to exist in the checkout. If the checkout is too shallow, then all packages will be considered changed.

GitLab shallow-clones with depth 20 by default, so without GIT_DEPTH: 0 you'll silently rebuild everything. On MR pipelines set TURBO_SCM_BASE: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME too, otherwise it compares against main which isn't what you want on a release branch.

On the "no dependsOn because we use JIT" point: still declare dependsOn for the real ordering (build needing ^build, tests needing build output). It's how turbo knows what can run in parallel, and it costs you nothing at runtime if deps are already compiled. inputs/outputs matter more than you'd think here as well, they're what makes the cache actually hit later if you turn it on.

The one thing that genuinely needs separate jobs is per-app env files or per-app deploy credentials. Do that with a normal job per app and --filter=app-name, not a generated child pipeline:

deploy:web:
  script: pnpm turbo run deploy --filter=web
  environment: production-web

Handful of static jobs, no pipeline generator to maintain.

[inikonorov]

Okay, thanks, also my thoughts

my CI/CD process is:

• install
• run eslint
• run prettier
• run unit tests
• run integration tests
• build test env
• build test storybook env
• deploy test env (x)
• deploy test storybook env (x)
• build prod env (x)
• deploy prod env (x)

x-marked jobs are required per-app env variables, so in my mind it's almost half of all jobs in every app and what's a real problem here - it's hard to truly understand which one app is running in CI/CD - you see dozens of jobs in every MR pipeline and if I changed web app, I don't want to run deploy:test job for every package in my monorepo - I want to run jobs only related to changed web app, so here I have only 2 options:

• check in every per-app job that this app is changed by npx turbo ls --affected
• generate child pipelines based on npx turbo ls --affected

if you use child pipeline, you guarantee 3 things:

• you run only that jobs, that are related with changed apps
• you see in CI/CD only changed apps (it's easier to observe than dozens of jobs from all apps)
• if CI/CD process varies from app to app - it's okay, you open child pipeline and see from what jobs your app CI/CD process consists of

if you know how to organize CI/CD process without child pipelines by with the same benefits - I'll be very happy to know

PS: maybe it's better for vercel extends docs about set up monorepo & gitlab ci, because I'm sure by 100% that I'm not alone with this thoughts & problems

Thank you very much!

[official-burak]

On your direct question — no, you can't get benefit #2 without a dynamic child pipeline, and that's a GitLab constraint rather than anything to do with turbo. A pipeline's job list is fixed when the pipeline is created, and rules:changes only accepts static path globs; nothing in rules can consult the output of a command, and there is no mechanism to remove an already-declared job at runtime. trigger:include:artifact is the only supported way to make the job set depend on a computed result. So keep the child pipelines. They're the right tool here, not a workaround for turbo.

What's worth changing is the division of labour, not the pipeline shape.

The generator should only decide which apps, never what runs. turbo.json keeps owning task ordering, and each child calls turbo run <task> --filter=<app> so turbo still expands dependsOn and pulls in the app's dependency closure. That's the split that resolves the conflict you described: the generator answers "is web in scope for this commit", turbo answers "what has to happen, and in what order, for web".

Why the static rules:changes alternative drifts. You can approximate app scoping with rules:changes:paths plus compare_to, but you have to hand-enumerate every internal dependency path for each app, and that list is exactly the graph turbo already computes. On a three-package fixture (web depends on @mono/ui, admin doesn't), a commit touching only packages/ui:

$ turbo ls --affected --output=json
@mono/ui  packages/ui
web       apps/web

admin is correctly absent and web is correctly present — a rules:changes block on apps/web/** would have missed it. Every new dependency edge silently invalidates the YAML, and the failure mode is a skipped deploy, which you find out about in production. That is the real argument for the generator, and it's a stronger one than pipeline ergonomics.

The generator input is that same JSON:

generate:
  stage: prepare
  variables:
    GIT_DEPTH: 0
    TURBO_SCM_BASE: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
  script:
    - pnpm install --frozen-lockfile
    - pnpm turbo ls --affected --output=json > affected.json
    - node scripts/generate-pipeline.mjs affected.json > child.yml
  artifacts:
    paths: [child.yml]

run-apps:
  stage: build
  trigger:
    include:
      - artifact: child.yml
        job: generate
    strategy: depend

TURBO_SCM_BASE (and TURBO_SCM_HEAD) override the comparison range, which you need because the default base is main — on a release branch that's the wrong answer. Verified on turbo 2.10.11: with TURBO_SCM_BASE=HEAD the affected set is empty, with TURBO_SCM_BASE=main it's the two packages above.

The thing that will actually cost you, given that you don't use the cache. One child pipeline per app means each child independently builds every shared package in its --filter closure. Two apps depending on packages/ui is two ui builds per commit; the waste scales with apps × shared deps, and it's invisible because every child looks reasonable on its own. Pipeline restructuring can't fix that — the children are separate runners with separate checkouts, so there's nothing to share.

You don't need Vercel Remote Cache for this. Turbo's local filesystem cache carried through GitLab's own cache: is enough:

variables:
  TURBO_CACHE_DIR: $CI_PROJECT_DIR/.turbo/cache

default:
  cache:
    key: turbo-$CI_COMMIT_REF_SLUG
    fallback_keys:
      - turbo-$CI_DEFAULT_BRANCH
    paths:
      - .turbo/cache

fallback_keys (GitLab 16.0+) is the part that matters: without it the first pipeline on a branch starts cold and you're back to rebuilding everything once per branch. With it, the second child that needs packages/ui restores it instead of rebuilding, and the per-app child structure stops costing anything.

This is also the point where the dependsOn/inputs/outputs entries you'd been skipping start paying for themselves — outputs is what turbo captures into the cache, so a task with no declared outputs restores as a cache hit with no artifacts, which looks like the cache is broken.

Verified against turbo 2.10.11.