How does nx affected decide what changed in a GitLab pipeline?

nx affected answers one question: which projects could be impacted by the commits in this pipeline? It works in three steps. First, it runs a git diff between a base SHA and a head SHA, passed as --base/--head or through the NX_BASE/NX_HEAD environment variables. Second, it maps each changed file to the project that owns it. Third, it walks the project graph to add every project that depends on those projects. Only that set gets linted, tested or built.

pipeline source ──> SHA selection ──> git diff base..head
 (MR / branch)       (NX_BASE,              │
                      NX_HEAD)               v
                                     changed files
                                             │
                                             v
targets <── affected projects <── project graph
(lint/test/build)                  (owners + dependents)

For backend and platform engineers running a large Nx monorepo on GitLab, this is how a pipeline stops rebuilding fifty services when one library changed. Fewer jobs and shorter runs mean faster review cycles and less runner time.

Both inputs have to be correct. If the base SHA is wrong for the pipeline type, the diff is wrong. It may be too wide and waste time, or too narrow and skip real work. That is why this tutorial picks the SHAs first and adds caching afterward. A fast cache cannot fix an incorrect diff.

The project graph matters just as much:

  • Undeclared dependencies. If a project reads generated code or shared config through a path Nx cannot detect, and you did not declare it as an implicit dependency, Nx cannot know to include that project.
  • Unowned files. Files outside any project may not map to anything.

In both cases, projects that should run are silently skipped. Treat that as a correctness bug, not a missed optimization: a green pipeline that never tested the broken code.

+--------------------+     +-------------------------+
| GitLab pipeline    |     | SHA selection           |
| source             |---->| NX_BASE / NX_HEAD       |
| (MR / branch)      |     | (--base / --head)       |
+--------------------+     +-------------------------+
                                        |
                                        v
                           +-------------------------+
                           | git diff base..head     |
                           | -> changed files        |
                           +-------------------------+
                                        |
                                        v
+--------------------+     +-------------------------+
| implicit deps +    |     | project graph           |
| file ownership     |---->| owners + dependents     |
| (gaps = skipped)   |     |                         |
+--------------------+     +-------------------------+
                                        |
                                        v
                           +-------------------------+
                           | affected projects       |
                           +-------------------------+
                                        |
                                        v
                           +-------------------------+
                           | targets                 |
                           | lint / test / build     |
                           +-------------------------+

How nx affected works in GitLab CI: the pipeline source selects base and head SHAs, git diff lists changed files, and the project graph maps them to owners and dependents to decide which targets run.

Should you use branch pipelines or merge request pipelines for Nx affected?

GitLab can start a pipeline for the same commit in two ways. A branch pipeline runs on every push to a branch and knows only the branch and commit. A merge request pipeline runs when a merge request is opened or updated and also exposes the target branch and the diff base through variables such as CI_MERGE_REQUEST_TARGET_BRANCH_NAME and CI_MERGE_REQUEST_DIFF_BASE_SHA. For nx affected, that difference matters: a branch pipeline has to guess what to compare against, while a merge request pipeline is told.

Aspect Branch pipeline Merge request pipeline
Trigger Any push to a branch MR created or updated
Knows target branch No Yes
Diff base available No, must be derived Yes, via predefined variables
Runs without an MR Yes No

If you keep GitLab's default behaviour and add merge request jobs, a single push to a branch with an open MR starts two pipelines. Avoid this with workflow:rules. Use one rule that matches $CI_PIPELINE_SOURCE == 'merge_request_event' and a second that matches $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH. With no other rules, pushes to feature branches start nothing until someone opens an MR. The default branch still runs after each merge.

Use merge request pipelines whenever changes reach the default branch through MRs. That covers most teams.

The remaining gap is semantic conflicts. Your branch can pass against an older target while a commit merged since then breaks the combination. Merged results pipelines, where your GitLab tier supports them, test a temporary merge commit of source and target. This narrows the gap, but the pipeline reruns whenever the target moves, so expect more CI minutes.

# .gitlab-ci.yml
# One pipeline per push: MR pipelines for feature work, branch pipelines
# only on the default branch. Feature-branch pushes without an MR run nothing.
workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

variables:
  # Full history so the base SHA exists locally for nx affected.
  GIT_DEPTH: 0

affected:
  image: node:20
  script:
    - npm ci
    - |
      if [ "$CI_PIPELINE_SOURCE" = "merge_request_event" ]; then
        # GitLab supplies the merge base with the target branch.
        BASE="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
      else
        # Default branch: compare with the commit before this push.
        BASE="$CI_COMMIT_BEFORE_SHA"
      fi
      # In a merged results pipeline, HEAD is the temporary merge commit,
      # so the same command tests source and target together.
      npx nx affected -t lint test build --base="$BASE" --head=HEAD

A .gitlab-ci.yml that uses workflow:rules to run only merge request pipelines and default-branch pipelines, then passes the MR diff base SHA to nx affected.

Which base SHA should Nx use in merge request and main-branch pipelines?

In merge request pipelines, set NX_BASE to CI_MERGE_REQUEST_DIFF_BASE_SHA and NX_HEAD to CI_COMMIT_SHA. The diff base SHA is the merge base of the source and target branches, so Nx only sees changes the branch actually introduced. If you compare against the target branch tip instead, every commit merged to main since the branch was cut appears as "changed". That inflates the affected set and makes the result depend on when the pipeline happened to run.

The trade-off is that a merge-base comparison never tests the branch against newer main work. Two MRs can each pass alone and still break together, for example when one renames a function that the other starts calling. You find that semantic conflict only after the merge.

On main, CI_COMMIT_BEFORE_SHA is the obvious choice, but it is weak:

  • It holds all zeros on some pushes.
  • It reflects only the previous push.
  • It skips changes whose pipelines failed or were cancelled. If push A breaks and push B fixes something unrelated, B's diff never retests A's projects.

Tracking the SHA of the last successful main pipeline closes that gap.

Base option Pipeline Strength Weakness
CI_MERGE_REQUEST_DIFF_BASE_SHA MR Isolates the branch's own changes Misses conflicts with newer main
Target branch tip MR Includes newer main work Inflated, time-dependent affected set
CI_COMMIT_BEFORE_SHA main Always available as a variable All zeros on some pushes; ignores failed or cancelled pipelines
Last successful main SHA main Covers everything since the last green build Needs lookup logic and permissions

Define an explicit fallback. If the base is empty, all zeros, or not present in the clone, skip affected and run targets for every project. A full run is slower, but it never silently skips a project.

#!/usr/bin/env bash
# Compute NX_BASE/NX_HEAD for GitLab CI, falling back to a full run when no usable base exists.
set -euo pipefail

ZERO_SHA="0000000000000000000000000000000000000000"
NX_HEAD="$CI_COMMIT_SHA"

if [ "${CI_PIPELINE_SOURCE:-}" = "merge_request_event" ]; then
  # Merge base of source and target: only the branch's own changes count as affected.
  NX_BASE="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-}"
else
  # Main: prefer the last successful main pipeline SHA, so failed or cancelled
  # pushes are retested. LAST_SUCCESSFUL_SHA is set by an earlier lookup step.
  NX_BASE="${LAST_SUCCESSFUL_SHA:-${CI_COMMIT_BEFORE_SHA:-}}"
fi

# A base is usable only if it is non-empty, not all zeros, and present in this clone.
# Shallow clones often lack older commits, so check before trusting it.
base_is_usable() {
  [ -n "$NX_BASE" ] && [ "$NX_BASE" != "$ZERO_SHA" ] \
    && git cat-file -e "${NX_BASE}^{commit}" 2>/dev/null
}

if base_is_usable; then
  echo "Affected run: base=$NX_BASE head=$NX_HEAD"
  npx nx affected -t lint test build --base="$NX_BASE" --head="$NX_HEAD"
else
  # No valid base: run every project. Slower, but nothing is skipped silently.
  echo "No usable base SHA (got '${NX_BASE}'); running all projects"
  npx nx run-many -t lint test build
fi

A CI shell step that uses CI_MERGE_REQUEST_DIFF_BASE_SHA in merge request pipelines and the last successful main SHA (falling back to CI_COMMIT_BEFORE_SHA) on main, and runs every project when the base is empty, all zeros, or missing from the clone.

How do you make sure the base commit exists in the GitLab clone?

GitLab runners clone with a limited fetch depth by default. The project's CI/CD settings control how many recent commits are fetched, and the GIT_DEPTH variable overrides that value. This keeps checkout fast, but it creates a gap for affected. If the merge request's target branch has moved on, or the feature branch has more commits than the depth allows, the base SHA is not in the clone. git diff then fails, and depending on how your script handles errors, Nx either aborts or produces a misleading project list.

You can close the gap in two ways:

  • GIT_DEPTH: 0 disables shallow cloning so the job gets full history. Every reachable SHA resolves, merge bases compute correctly, and the job needs no extra script logic. The cost is checkout time and runner disk, which grow with repository age and size.
  • Targeted fetch keeps a small default depth and then runs git fetch for the base commit or the target branch before calling Nx. This is faster on large repositories, but it adds failure points:
    • The server must permit fetching that ref.
    • If Nx diffs against a merge base, a depth-1 fetch of the base can leave the two histories disconnected. You may need to deepen the clone until a common ancestor exists.

Either way, verify the base before calling Nx. git cat-file -e "$BASE^{commit}" or git rev-parse --verify --quiet "$BASE^{commit}" exits non-zero when the commit is missing. Use that exit code to trigger the full-run fallback described above instead of letting affected guess.

nx-affected:
  image: node:20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    # Option A: full history. No extra script, but slower checkout on big repos.
    # GIT_DEPTH: "0"
    # Option B (used below): shallow clone, then fetch only what Nx needs.
    GIT_DEPTH: "20"
  script:
    - npm ci
    - BASE="$CI_MERGE_REQUEST_DIFF_BASE_SHA"
    # Fetch the target branch rather than a raw SHA. Some servers refuse SHA fetches.
    - git fetch --depth=50 origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" || echo "target fetch failed"
    # Deepen a bounded number of times until base and HEAD share an ancestor.
    - |
      for attempt in 1 2 3; do
        git merge-base "$BASE" HEAD >/dev/null 2>&1 && break
        git fetch --deepen=100 origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" || break
      done
    # Fail fast: run affected only if the base commit exists and connects to HEAD.
    - |
      if git cat-file -e "${BASE}^{commit}" 2>/dev/null \
         && git merge-base "$BASE" HEAD >/dev/null 2>&1; then
        npx nx affected -t lint test build --base="$BASE" --head=HEAD
      else
        echo "Base $BASE missing or disconnected; running all projects"
        npx nx run-many -t lint test build
      fi

A GitLab merge request job that keeps a shallow clone, fetches and deepens the target branch until a merge base exists, checks the base commit with git cat-file, and falls back to a full run when the check fails. It also shows GIT_DEPTH: "0" as the simpler full-history alternative.

How should you configure GitLab cache for node_modules and the Nx cache?

Use two separate cache entries, because the two directories change at very different rates.

Dependencies. Key the dependency cache with cache:key:files pointing at your lockfile (package-lock.json, pnpm-lock.yaml, or yarn.lock). The key then changes only when dependencies change, so most pipelines restore an exact match. With pnpm, cache the store directory rather than node_modules. The store is content-addressed and links quickly into place, while a cached node_modules tree can be large and slow to archive.

Nx cache. Give the Nx local cache directory its own entry. This is .nx/cache by default, so check nx.json for a custom cacheDirectory. Set policy: pull-push on one job, typically the main-branch pipeline. Set policy: pull on merge request jobs. This stops many parallel MR jobs from re-uploading near-identical archives, and it stops one branch's artifacts from overwriting another's.

Costs to plan for. GitLab cache is best-effort. It is scoped to the runner and the cache configuration, so a job that lands on a different runner gets a miss unless the runners share a distributed cache backend. Across a large autoscaled pool, expect frequent misses. Budget pipeline time as if the cache were cold, and treat hits as a bonus.

The Nx cache directory also grows without limit. Each archive upload and download gets slower until restoring the cache costs more than recomputing the tasks. Prune it on a schedule:

  • Run nx reset periodically.
  • Rotate the cache key, for example by adding a manually bumped prefix.

Alternative: remote caching. If cross-runner hit rates matter, a remote task cache can work better. It stores individual task outputs centrally rather than whole directory archives, and that removes the archive upload and download step.

Putting it together: a minimal .gitlab-ci.yml for nx affected

The pipeline has three parts, and each part prevents a specific failure.

Workflow rules limit the pipeline to merge request events and to the default branch. Without them, a branch with an open merge request triggers both a branch pipeline and a merge request pipeline, and the two compute different bases.

A setup job resolves the base and head SHAs once. It writes NX_BASE and NX_HEAD to a file that it publishes as a dotenv report artifact. Downstream jobs that depend on this job receive the values as ordinary environment variables, so every job compares against the same commit. A shared script sourced in each job also works. The risk with a script is that each job recomputes the SHAs, and a recomputation can drift if the target branch moves during the pipeline.

Target jobs run nx affected with --parallel. Nx then schedules work across projects inside one job. This avoids one GitLab job per project, which would repeat installation for every project.

Lint, test and build can run in one job or in separate jobs:

Layout Strengths Costs
One job, -t lint test build Short config, one install and cache restore One red status for any failure; retrying reruns everything not cached
One job per target Clear failure signal, retry only the failed target Repeated install, cache restore and checkout per job

Whichever layout you choose, have each job print NX_BASE and NX_HEAD and run nx show projects --affected before any target executes. If the base is wrong, the job log shows the wrong comparison immediately. Without these checks, the only symptom may be a green pipeline that tested nothing.

When should you avoid nx affected in GitLab CI, and what are the alternatives?

nx affected only pays off when most merge requests touch a small part of the graph. Several common situations break that assumption:

  • Frequent root-level changes. Edits to nx.json or shared config, and lockfile changes depending on how Nx is configured, can mark most or all projects affected. Teams that change these often get full runs plus the overhead of computing the comparison.
  • Dependency-update merge requests. Bot-generated upgrades usually touch the lockfile and cost about as much as a full run.
  • Small repositories. If a full run finishes in a few minutes, maintaining base SHAs and fetch depth costs more effort than it saves.
  • Unreliable project graphs. Undeclared dependencies, such as runtime file reads, generated code, or implicit imports, let real breakage skip CI. That is the green-but-wrong result described above.
Approach Correctness CI cost Maintenance effort
Always run all targets Highest Highest Lowest
Affected plus scheduled full runs High; gaps caught within one schedule interval Low to moderate Moderate
Merged results pipelines Tests the merged state, not only the branch Same as the strategy it wraps Low
rules:changes path filters Only as good as hand-written paths Low High; paths drift as the repo changes

Illustrative estimate. These inputs are assumed, not measured: 40 merge request pipelines per day, a 25-minute full run, a 10-minute average affected run, and engineers actively waiting on one quarter of pipelines.

  • Waiting time saved: 40 × 15 minutes × 0.25 = 150 minutes per day, or about 12.5 hours per week.
  • Maintenance cost: about 2 hours per week spent fixing base SHA and graph issues.
  • Result with frequent root changes: if 60% of merge requests touch root files, the saving drops to about 5 hours per week. That is still positive, but the margin is much smaller.

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 affected, 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.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

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.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • 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.