Who should use an Nx affected pipeline in GitLab CI?

This setup suits teams that keep several apps and libraries in one Nx workspace hosted on GitLab, where a full lint, test and build run is slow enough to delay merge requests. The more independent projects the workspace has, the smaller the typical affected set is relative to the whole graph, and the more each pipeline saves.

It also requires someone who can own the plumbing. Correct results depend on an accurate project graph, a base SHA that GitLab variables or the Pipelines API can supply, and a clone that actually contains that base. A team that can keep implicitDependencies and named inputs up to date, and can maintain a short shell script, gets the most from it.

It is a poor fit in three cases:

  • Small workspaces. If a full run already finishes in a few minutes, the SHA logic costs more to maintain than it saves.
  • Workspaces whose graph Nx cannot see. Heavy use of runtime-only coupling, generated code or shared config that is not declared as an input means affected runs will skip work that should run.
  • Teams that cannot grant an API token. Without read access to the Pipelines API, default-branch pipelines fall back to weaker bases, which reduces both safety and savings.

How does nx affected decide what to run?

nx affected answers one question: which projects could behave differently between two commits? It gets the answer in three steps.

  1. Find changed files. Nx diffs the head commit against the merge base of base and head. You pass these as --base and --head, or set the NX_BASE and NX_HEAD environment variables. If you set neither, Nx uses the defaultBase from nx.json for base and compares against the working tree, so uncommitted changes count too.
  2. Map files to projects. Each changed path is assigned to the project whose root contains it. Some root-level files get special handling. For example, a lockfile change marks the projects that depend on the changed packages.
  3. Add dependents. Nx walks the project graph in reverse. A change to a shared library therefore also selects every app and library that imports it.

This saves the most in monorepos where a full build or test run takes long enough to slow down every merge request. The cost is that correctness now depends on two things you have to maintain.

The base commit. If the base is too recent, such as the parent of the latest push, the diff misses earlier commits on the branch, and projects are skipped silently with a green pipeline. If the base is too old or unreachable, nearly everything is marked affected, or Nx fails to resolve the commit, and you lose the benefit.

The graph. Nx only knows what it can infer from imports and configuration. Several gaps lead to under-testing:

  • Runtime relationships, such as a service calling another over HTTP, need to be declared as implicitDependencies.
  • Global files like shared tsconfig or lint configs need to be listed in named inputs such as sharedGlobals.
  • Targets whose inputs omit files they actually read will not be selected when those files change.
#!/usr/bin/env bash
set -euo pipefail

export NX_BASE="${CI_MERGE_REQUEST_DIFF_BASE_SHA}"
export NX_HEAD="${CI_COMMIT_SHA}"

git fetch --no-tags origin "${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}"

npx nx show projects --affected

npx nx affected -t lint test build --base="$NX_BASE" --head="$NX_HEAD"

Pins nx affected to the merge request's diff base and the pipeline commit, fetches the base so it can be resolved, and logs the selected projects before running lint, test and build.

How does the whole GitLab CI setup work end to end?

The pieces in the rest of this article fit together into one flow that runs in every pipeline:

  1. GitLab decides whether a pipeline runs. workflow:rules allows only merge request pipelines and pushes to the default branch, so each commit gets exactly one pipeline and one base.
  2. The runner clones the repository. Either with full history (GIT_DEPTH: "0") or shallowly, followed by a targeted fetch of the target branch.
  3. A shared script picks the SHAs. NX_HEAD is always CI_COMMIT_SHA. NX_BASE is CI_MERGE_REQUEST_DIFF_BASE_SHA in merge request pipelines, or the SHA of the last successful default-branch pipeline from the Pipelines API on main.
  4. The script verifies the base. git cat-file -e and git merge-base confirm the commit exists locally and shares history with head. If either check fails, the job is flagged to run everything.
  5. Caches are restored. The dependency cache is keyed on the lockfile, and the Nx computation cache on the branch with the default branch as fallback.
  6. Nx computes and runs the affected set. It diffs base and head, maps changed files to projects, adds dependents from the project graph, and runs the requested targets for only those projects. Tasks whose inputs hash to a cached result are replayed instead of executed.
  7. The job logs what it chose. One line with the pipeline source, the branch of logic taken and both SHAs, so a skipped or over-broad run can be reproduced locally with nx show projects --affected.

A scheduled full build sits alongside this flow to catch anything the project graph misses.

Why doesn't GitLab have an equivalent of nx-set-shas?

nx-set-shas is a GitHub Action, not part of Nx itself. It does two jobs. On a push to the main branch, it queries the GitHub API for the most recent successful workflow run on that branch and uses that run's commit as NX_BASE. A failed or cancelled run therefore never becomes the baseline, and its changes are tested again on the next push. On a pull request, it uses the merge base between the PR head and the target branch. It exports both values as NX_BASE and NX_HEAD for the rest of the job.

GitLab has no maintained equivalent, so you build the same logic from predefined CI/CD variables and the Pipelines API. Each available SHA source has different trade-offs:

SHA source Accuracy Cost Failure mode
CI_MERGE_REQUEST_DIFF_BASE_SHA Matches the diff shown in the MR Free, already set Only set in merge request pipelines. Empty in branch pipelines.
Last successful pipeline via API Matches nx-set-shas behaviour on main One API call and a token with API read access Missing token, no prior green pipeline, or the commit is absent from a shallow clone
CI_COMMIT_BEFORE_SHA Only covers the most recent push Free All zeros on a new branch. If the previous pipeline failed, its changes are skipped silently.
Full run (no base) Complete Highest compute None, apart from time and runner minutes

CI_COMMIT_BEFORE_SHA causes the most trouble. It looks correct when you test it, but it gives a green pipeline that never re-ran the work a failed pipeline left untested.

Which GitLab pipelines should run nx affected, and with which base?

Run Nx in two pipeline types only: merge request pipelines and pushes to the default branch. In workflow:rules, accept $CI_PIPELINE_SOURCE == "merge_request_event", then drop branch pipelines with $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS set to when: never, then accept $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH. Without the middle rule, a push to an MR branch starts two pipelines for the same commit. Each computes a different base, so their affected sets disagree, and either one can be the result reviewers end up looking at.

For MR pipelines, set NX_BASE to CI_MERGE_REQUEST_DIFF_BASE_SHA and NX_HEAD to CI_COMMIT_SHA. The diff base is the merge base, the commit where the branch left the target. If you use the target branch tip instead, every project changed on main since the branch was created counts as affected. Merged results pipelines need extra care. There, CI_COMMIT_SHA is a synthetic merge commit that exists only for that pipeline. Its inputs include whatever recently landed on the target, so task hashes match earlier runs less often and remote cache hits drop.

On the default branch, query the pipelines API for the most recent successful pipeline on that ref and use its SHA as the base. The job needs a token with read_api scope, stored as a masked variable. Read-only access is enough, so do not grant write scopes. If the query returns nothing, fall back to CI_COMMIT_BEFORE_SHA. If that value is all zeros (a first push or a new branch), there is no usable base, so run every target.

Use the last successful pipeline rather than the previous push for a specific reason. With the previous push as the base, a broken commit followed by an unrelated fix compares only against the broken commit, so the projects that failed are never tested again.

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    # Drop branch pipelines while an MR is open: one commit, one pipeline, one base
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

nx-affected:
  image: node:20
  variables:
    GIT_DEPTH: "0"  # full history so the base SHA exists locally
  script:
    - npm ci
    - |
      ZERO=0000000000000000000000000000000000000000
      if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
        # Merge base, not target tip. In merged results pipelines CI_COMMIT_SHA
        # is a synthetic merge commit, so expect fewer remote cache hits.
        NX_BASE="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
      else
        # Last green pipeline on the default branch, so a red-then-fixed
        # sequence still retests what broke. NX_READ_API_TOKEN: masked, read_api only.
        NX_BASE=$(curl -sf --header "PRIVATE-TOKEN: $NX_READ_API_TOKEN" \
          "$CI_API_V4_URL/projects/$CI_PROJECT_ID/pipelines?ref=$CI_DEFAULT_BRANCH&status=success&per_page=1" \
          | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const p=JSON.parse(s||"[]");process.stdout.write(p[0]?.sha||"")})' || true)
        NX_BASE="${NX_BASE:-$CI_COMMIT_BEFORE_SHA}"
      fi
      export NX_BASE NX_HEAD="$CI_COMMIT_SHA"
      if [ -z "$NX_BASE" ] || [ "$NX_BASE" = "$ZERO" ]; then
        # First push or new branch: no usable base, run everything
        npx nx run-many -t lint test build
      else
        npx nx affected -t lint test build --base="$NX_BASE" --head="$NX_HEAD"
      fi

A .gitlab-ci.yml that runs only MR and default-branch pipelines, uses the MR merge base or the last successful default-branch pipeline SHA as NX_BASE, falls back to CI_COMMIT_BEFORE_SHA, and runs every target when no usable base exists.

How do you make sure the clone contains the base commit?

GitLab runners clone shallowly by default. The fetch depth comes from GIT_DEPTH or the project's CI/CD shallow-clone setting, and on recent GitLab versions it is a small number of commits. If the merge request's diff base or the previous push sits deeper than that, the SHA you hand to Nx is not in the local object database. nx affected then fails on the comparison instead of quietly running nothing. A shallow clone can also cut the history between base and head, so even a fetched base can leave git merge-base without a common ancestor.

There are two fixes:

Approach How Cost Failure mode
Full clone Set GIT_DEPTH: "0" on affected jobs Clone time and storage grow with history size Rarely fails
Targeted fetch git fetch the target branch (CI_MERGE_REQUEST_TARGET_BRANCH_NAME), then deepen until the base is reachable Fast on large repositories Depends on the remote having the ref, and on depth being sufficient

A full clone is the safer default. Switch to targeted fetches only when clone time is a measured problem. If you do switch, treat the fetch as best-effort and never assume it worked.

Before calling Nx, check the base with git cat-file -e "$NX_BASE^{commit}". If the check fails, fall back to running every target.

Two cases make that check fail regularly:

  • Fork merge requests. The pipeline runs against the fork, which may not carry the target branch, or may carry an outdated copy of it.
  • Stale or force-pushed target branches. The recorded base SHA no longer exists on the remote.

In both cases, running everything is slower but correct. Guessing a base is not.

affected:
  image: node:20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    # Targeted-fetch variant. Use GIT_DEPTH: "0" instead for a full clone.
    GIT_DEPTH: "50"
  script:
    - npm ci
    - |
      NX_BASE="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-}"
      NX_HEAD="$CI_COMMIT_SHA"
      TARGET="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
      # Best-effort fetch of the target branch. It can fail on fork MRs or deleted refs.
      git fetch --no-tags origin "+refs/heads/${TARGET}:refs/remotes/origin/${TARGET}" || true
      # Deepen in bounded steps until base and head share history.
      for i in 1 2 3 4 5; do
        git merge-base "$NX_BASE" "$NX_HEAD" >/dev/null 2>&1 && break
        git fetch --no-tags --deepen=200 origin "+refs/heads/${TARGET}:refs/remotes/origin/${TARGET}" || break
      done
      # Never assume the fetch worked. Verify the base object and a common ancestor.
      if [ -n "$NX_BASE" ] \
         && git cat-file -e "${NX_BASE}^{commit}" 2>/dev/null \
         && git merge-base "$NX_BASE" "$NX_HEAD" >/dev/null 2>&1; then
        npx nx affected -t lint test build --base="$NX_BASE" --head="$NX_HEAD"
      else
        # Fork MR, stale or force-pushed target: slower but correct.
        echo "Base '${NX_BASE}' not reachable; running all targets"
        npx nx run-many -t lint test build
      fi

A GitLab CI merge request job that fetches the target branch, deepens a shallow clone in bounded steps, checks the base with git cat-file -e and git merge-base, and falls back to running every target when the base cannot be reached.

Writing one script that sets NX_BASE and NX_HEAD for every job

The script has three jobs: pick a base, prove the base exists in the clone, and report what it chose. Order the branches by trust.

  1. Merge request pipelines. When CI_PIPELINE_SOURCE is merge_request_event, use CI_MERGE_REQUEST_DIFF_BASE_SHA as the base. It is the merge base GitLab already computed, so no API call is needed.
  2. Default-branch pipelines. Query the pipelines API for the most recent successful pipeline on CI_DEFAULT_BRANCH and take its SHA. CI_JOB_TOKEN may not have permission to read pipelines, so use a masked CI/CD variable holding a token with read access.
  3. Fallbacks. If the API returns nothing, or git cat-file -e shows the commit is missing from the clone, set a flag that tells the job to run everything instead of computing affected projects.

Set NX_HEAD to CI_COMMIT_SHA in every case and export both variables. Nx reads them directly, so the nx affected commands need no extra flags.

Put the script in the repository and call it from a hidden job such as .nx-affected. Every affected job then uses extends to inherit it. A top-level default: before_script also works, but any job that defines its own before_script silently replaces the default instead of adding to it. That is how one job ends up with a different base from the others. extends makes the dependency visible in the job definition.

Before exiting, print one line with the pipeline source, the branch that was taken, and both SHAs. When someone asks why a library was skipped or the whole graph rebuilt, the job log answers immediately. Reproducing it locally is then one nx show projects --affected run with the same two SHAs, with no need to re-run the pipeline.

NX_HEAD="$CI_COMMIT_SHA"
NX_BASE=""
NX_RUN_ALL=false
branch_taken="none"

if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
  # GitLab already computed the merge base; trust it first.
  NX_BASE="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
  branch_taken="mr-diff-base"
elif [ "$CI_COMMIT_BRANCH" = "$CI_DEFAULT_BRANCH" ]; then
  # Last successful pipeline on the default branch (API returns newest first).
  NX_BASE=$(curl --silent --fail \
    --header "PRIVATE-TOKEN: $NX_API_TOKEN" \
    "$CI_API_V4_URL/projects/$CI_PROJECT_ID/pipelines?ref=$CI_DEFAULT_BRANCH&status=success&per_page=1" \
    | jq -r '.[0].sha // empty')
  branch_taken="last-successful-default"
fi

if [ -z "$NX_BASE" ] || ! git cat-file -e "${NX_BASE}^{commit}" 2>/dev/null; then
  NX_RUN_ALL=true
  branch_taken="${branch_taken}+fallback-run-all"
fi

export NX_BASE NX_HEAD NX_RUN_ALL

echo "nx-base: source=$CI_PIPELINE_SOURCE branch=$branch_taken base=${NX_BASE:-<none>} head=$NX_HEAD run_all=$NX_RUN_ALL"

A sourced shell script that chooses NX_BASE from the MR diff base or the last successful default-branch pipeline, falls back to a run-everything flag when the commit is missing, and logs one line with the SHAs it picked.

How should you cache dependencies and the Nx computation cache in GitLab CI?

Dependencies and the Nx computation cache have different invalidation rules, so give them separate cache entries. The package manager store should change only when the lockfile changes. Use cache:key:files pointing at the lockfile. The Nx cache changes with every commit, so it needs a branch-aware key. In that key, use $CI_DEFAULT_BRANCH as the fallback key so a new merge request starts from the main-branch entries instead of starting cold.

Give every job policy: pull and let one job per cache use pull-push. Without a single writer, parallel jobs race to upload archives and the last one wins. Restrict the Nx cache writer to the default branch. If merge request pipelines could write a shared entry, an untrusted branch could poison outputs that main later replays.

Don't hardcode the Nx cache path. Its default location has moved between Nx versions, so read cacheDirectory from nx.json or check what your installed version uses.

Concern Dependency cache Nx cache
Key Lockfile hash Branch, with the default branch as fallback
Writer One install job Default-branch job only
Growth Bounded by the lockfile Grows with every run, so prune or rotate keys

GitLab cache only goes as far as the runner's cache backend reaches, and archives grow until you rotate the key. A remote Nx cache shares individual task results across all runners, so it usually gets higher hit rates.

Illustrative estimate. These inputs are assumed: 40 merge request pipelines a day, and a full run takes 30 minutes. Affected detection cuts each run to 25% of the graph, or 7.5 minutes. If half of those tasks then hit the cache, each pipeline takes about 4 minutes. That's 160 CI minutes a day instead of 1,200.

What are the alternatives to nx affected in GitLab CI?

Affected runs are one way to avoid doing unnecessary work. The alternatives differ in how much they rely on the project graph and how much setup they need.

Alternative How it works Strength Weakness
Full run every time (nx run-many) Run every target for every project, relying on the Nx computation cache to skip unchanged tasks No base SHA to manage, nothing skipped by mistake Every task still has to be hashed and its cached output restored, and cache misses cost full compute
GitLab rules:changes per job Each job lists path globs and runs only when matching files change, optionally with compare_to set to a ref Native to GitLab, no extra tooling Globs are maintained by hand and know nothing about dependents, so a change to a shared library does not trigger the apps that import it unless you list it explicitly
Child pipelines per project A parent pipeline uses trigger:include with rules:changes to start a separate pipeline for each project directory Clear ownership and separate pipeline views per project Same dependency blindness as rules:changes, plus more YAML to keep in sync with the workspace
Full run with GitLab parallel: Split a complete run across several jobs Simple and complete Pays checkout, install and cache restore on every node, every time
Split the repository Move projects into separate repositories, each with its own pipeline Each pipeline is naturally small Cross-project changes need coordinated merge requests and version bumps, which removes the main reason to use a monorepo

The main advantage of nx affected over the GitLab-native options is that it derives dependents from the project graph rather than from hand-written globs. The main advantage of a plain full run is that it has no base SHA to get wrong. Many teams combine the two: affected runs on merge requests and the default branch, with a scheduled full run as the safety net.

When should you split, skip or avoid nx affected in GitLab CI?

Start with parallelism inside a single job. Pass --parallel to nx affected -t lint test build with a value matched to the runner's CPU count, for example from nproc. If you set it higher than the CPU count, tasks compete for the same cores and memory. If you set it lower, the cores you pay for sit idle.

Splitting across GitLab parallel jobs

GitLab's parallel: keyword can fan tasks out across several jobs using CI_NODE_INDEX and CI_NODE_TOTAL. This balances poorly when one project dominates the affected set. Its build lands on a single node, and that node finishes long after the others. Every node also repeats checkout, dependency install and cache restore, so the fixed overhead grows with each node you add. Split only when the affected work is wide and fairly even.

When nothing is affected

Before you run tasks, check the affected set with nx show projects --affected. If it is empty, log a line such as "No projects affected between NX_BASE and NX_HEAD" and exit 0. A green job with an explicit reason is easier to audit than one that stays silent.

When to avoid affected-only runs

  • Small repos: if a full run takes a few minutes, the SHA logic costs more to maintain than it saves.
  • Untrustworthy project graphs: undeclared dependencies, shared config files or generated code can hide real impact from Nx.
  • Release pipelines: tag pipelines (CI_COMMIT_TAG) should build everything they ship.

Add a scheduled full build (CI_PIPELINE_SOURCE == "schedule") to catch the gaps that affected detection misses.

Overall, affected runs save CI time on every merge request. The cost is a SHA script that needs an owner, along with a periodic full run to keep it honest.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nx gitlab ci, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.