How does nx affected work in GitLab CI?
nx affected answers one question: given two commits, which projects could have changed behavior? It runs a git diff between --base and --head, which is effectively the merge base of the two refs compared against the head commit. It maps each changed file to the project that owns it through the project graph, then walks the graph in reverse to add every project that depends on those projects. The target you request, such as test, lint or build, runs only for that set.
How it works, step by step
- Resolve the range. Nx takes
--baseand--head. In GitLab CI you supply both from predefined variables or from a SHA you computed earlier in the job. - Diff with git. Nx asks git for the files that changed between the merge base of the two refs and the head commit. This step needs both commits and their shared ancestor in the local clone.
- Map files to projects. Each changed file is assigned to the project whose root contains it. Files that belong to no project, such as root config or the lockfile, are handled separately and can affect many or all projects.
- Expand to dependents. Nx walks the project graph in reverse and adds every project that depends on a changed project, directly or transitively. It also adds projects linked through
implicitDependencies. - Run the target. The requested targets run for the resulting set. Any task whose input hash matches a cached result is replayed from the cache instead of executed.
The diff happens before any Nx logic, so the two git inputs matter more than any Nx flag. If the base is too old, the change set grows until you are running most of the monorepo again. If the base is too new, changes go untested and the pipeline still passes. If the clone is too shallow to contain the base commit, git cannot compute the diff and the job fails. Later sections cover base selection, tracking the last successful commit and clone depth.
The payoff is largest for backend and platform teams with many services and shared libraries, where a full test or build run takes long enough to slow merge requests.
The graph has limits. Changes to files outside any project, such as nx.json, root config files or the package lockfile, can mark every project as affected. Declared implicitDependencies widen the set on purpose. Some coupling is invisible to Nx: services that talk over HTTP, a shared database schema, or files read at runtime that no project declares as an input. Nx will not select the consumers of those changes, so cover them with explicit dependencies or separate checks.
GitLab CI job: clone must be deep enough to contain the base commit
+------------------+ +------------------+
| --base | | --head |
| merge-base SHA | | head commit |
+--------+---------+ +--------+---------+
| |
+-----------+------------+
v
+----------------------+
| git diff base..head |
+----------+-----------+
| changed files
v
+----------------------+ +------------------------------+
| project graph: |<----| nx.json, root config, |
| file -> owning proj | | lockfile: may mark ALL |
+----------+-----------+ +------------------------------+
| directly changed projects
v
+----------------------+ +------------------------------+
| reverse graph walk: |<----| implicitDependencies widen |
| add all dependents | | the set on purpose |
+----------+-----------+ +------------------------------+
| affected set
v
+----------------------+ +------------------------------+
| run target: test, | | NOT in graph: HTTP calls, |
| lint, build | | DB schema, runtime files |
+----------------------+ +------------------------------+
nx affected diffs the base against the head with git, maps each changed file to the project that owns it, adds every dependent project, and runs the target for that set. Global files and implicitDependencies widen the set, while coupling outside the graph is never selected.
When should you use nx affected in GitLab CI?
Use it when most changes touch a small part of the workspace and a full run is slow enough to matter. Typical signs:
- Many projects, mostly independent. A monorepo with dozens of services and libraries where a typical merge request edits one or two of them.
- Full pipelines are a bottleneck. Developers wait on lint, test and build for code they did not touch, or runner capacity is regularly saturated.
- The project graph is accurate. Dependencies are expressed as imports or declared in project configuration, so Nx can see them. Coupling through HTTP, shared schemas or runtime files is either declared through
implicitDependenciesandinputs, or covered by separate checks. - Merge request pipelines are the main feedback loop. MR pipelines have a well-defined base (
CI_MERGE_REQUEST_DIFF_BASE_SHA), which makes affected selection both reliable and easy to set up. - You can afford the git setup. At least the job that computes affected projects can get enough history, either through
GIT_DEPTH: 0or a targeted fetch.
A common, low-risk starting point is affected selection on merge requests only, with full runs on the default branch and for releases.
When should you avoid nx affected?
Skip it, or limit it, when selection is likely to be wrong or the savings are small:
- Small repositories. If a full run already finishes quickly, the effort of resolving base SHAs and debugging selection costs more than it saves. Run everything and rely on the Nx cache.
- Heavy implicit coupling. Code generation, shared configuration read at runtime, services that depend on each other only over the network, or a shared database schema. Nx cannot see these links, so affected selection can skip projects that break.
- Release and deploy pipelines. A release build should verify the whole artifact set it ships. Use
nx run-manythere. - Pipelines without a trustworthy base. Scheduled, web, trigger and API pipelines have no reliable previous commit. Run everything.
- Frequent global changes. If most commits touch the lockfile,
nx.jsonor root config, nearly every project is marked affected anyway, and you pay the setup cost for no reduction. - No way to get the base commit locally. If runner constraints force a very shallow clone and you cannot add fetch logic, the job will fail or select the wrong set.
The simpler alternatives are to always run everything and lean on the Nx cache, or to use GitLab rules:changes path filters for coarse, per-directory job selection.
How does nx affected save engineering time?
The savings come from three places:
- Less work per pipeline. Unaffected projects are not linted, tested or built. Merge requests that touch one service get feedback in roughly the time it takes to verify that service and its dependents.
- Cache replays for the work that remains. When an affected task's inputs match a previous run, Nx restores its logs and outputs instead of executing it. This helps most when the cache persists between pipelines.
- Fewer unrelated failures. Flaky or slow tests in projects you did not touch no longer block your merge request, so less time goes into reruns and triage of failures you did not cause.
Illustrative estimate: assume a workspace of 40 projects where a full lint test build run takes 30 runner minutes, evenly spread across projects. Assume a typical merge request edits one library with 5 dependents, so 6 projects are affected. The affected run then needs about 6/40 of the work, roughly 4.5 runner minutes, before any cache hits. A change to the lockfile or nx.json that marks every project as affected gets no reduction.
Subtract the costs from that figure: the extra clone depth for the affected job, the time to build and maintain base-SHA resolution, and occasional debugging when the selection looks wrong. These are mostly one-time costs, but they are why small repositories rarely benefit.
Which base SHA should you use for each GitLab pipeline type?
GitLab exposes what triggered a pipeline in CI_PIPELINE_SOURCE, and each value calls for a different base. The head is almost always CI_COMMIT_SHA. The base is the commit Nx diffs against.
CI_PIPELINE_SOURCE |
Base | Head |
|---|---|---|
merge_request_event |
CI_MERGE_REQUEST_DIFF_BASE_SHA |
CI_COMMIT_SHA |
push on default branch |
Last successful commit (next section) | CI_COMMIT_SHA |
schedule, web, trigger, api |
None reliable, so run everything | CI_COMMIT_SHA |
CI_COMMIT_BEFORE_SHA looks like a natural base for pushes, but it is unreliable. It is forty zeros for the first push of a new branch and for several non-push triggers. It also covers only the most recent push. If the previous pipeline failed or was cancelled, that push's changes never get re-tested.
In merged results pipelines, CI_COMMIT_SHA is a temporary merge commit of the source branch into the target. The diff base SHA is still an ancestor of that commit, so the range includes everything the MR introduces. It may also include target-branch commits that landed after the branch forked. That widens the selection but never drops a change.
The resolution script reads the pipeline source and picks a base. It then checks that the base is non-empty, is not all zeros, and exists locally (git cat-file -e "$BASE^{commit}"). If any check fails, it falls back to nx run-many across all projects.
The two failure modes are not symmetric:
- A base that is too old costs extra compute but stays correct.
- A base that is too new silently skips affected projects, and the pipeline reports green on untested code.
When in doubt, choose the older base.
#!/usr/bin/env bash
set -euo pipefail
TARGETS="lint,test,build"
HEAD="${CI_COMMIT_SHA}"
BASE=""
case "${CI_PIPELINE_SOURCE:-}" in
merge_request_event)
# Fork point of the MR. Still an ancestor of the temporary merge commit
# in merged results pipelines, so no MR change falls outside the range.
BASE="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-}"
;;
push)
# Expected to be set by an earlier step that finds the last green commit
# on the default branch. Do NOT use CI_COMMIT_BEFORE_SHA here.
if [ "${CI_COMMIT_BRANCH:-}" = "${CI_DEFAULT_BRANCH:-}" ]; then
BASE="${LAST_SUCCESSFUL_SHA:-}"
fi
;;
*)
# schedule, web, trigger, api: no trustworthy base, so leave BASE empty.
;;
esac
if [ -z "$BASE" ] || [[ "$BASE" =~ ^0+$ ]] || ! git cat-file -e "${BASE}^{commit}" 2>/dev/null; then
echo "Base unresolved for source '${CI_PIPELINE_SOURCE:-unknown}'; running all tasks."
npx nx run-many -t "$TARGETS"
exit 0
fi
echo "Affected range: ${BASE}..${HEAD}"
npx nx affected -t "$TARGETS" --base="$BASE" --head="$HEAD"
A shell script that picks the Nx base SHA from CI_PIPELINE_SOURCE and verifies it is non-empty, not all zeros, and present locally, falling back to nx run-many if any of those checks fails; LAST_SUCCESSFUL_SHA is assumed to be set by an earlier step.
How do you track the last successful commit on the default branch?
GitLab has no predefined variable for "the SHA of the last green pipeline on this branch," so you have to derive one. Two patterns are common.
Query the pipelines API. Early in the job, request the most recent pipeline with status=success on the default branch and use its sha as the base. This is read-only, but it needs a credential that can list pipelines. CI_JOB_TOKEN has a deliberately restricted scope that has changed over time, so check that it permits this call on your instance before you rely on it. If it does not, use a project access token with read access, stored as a masked variable.
Move a git ref after a green run. A final job force-pushes a tag such as nx-last-green to CI_COMMIT_SHA, and later pipelines fetch that tag as the base. This needs write access to the repository. That credential is broader than a read-only API token, and every pipeline that can reach it can rewrite refs.
| Pipelines API | Moving tag | |
|---|---|---|
| Credential | Read access to pipelines | Write access to the repo |
| Credential surface | Smaller | Larger |
| Concurrency risk | Low; reads the state GitLab records | Out-of-order pipelines can move the tag backwards or past untested commits |
| Extra moving parts | One API call | A dedicated job plus a tag fetch |
The tag pattern's race condition is real. If an older pipeline finishes after a newer one, it moves the marker to its own SHA. Serialise the tag job with a resource_group, or only move the tag forward when the new SHA is a descendant of the current one.
If neither pattern is worth the credentials, use a simpler option. You can diff against HEAD~1 or CI_COMMIT_BEFORE_SHA. Note that CI_COMMIT_BEFORE_SHA is all zeros for new branches and for some pipeline types. Either way, a failed commit's changes can be skipped on the next push. Alternatively, run every target on the default branch and reserve nx affected for merge requests.
nx-affected:
image: node:20
variables:
GIT_DEPTH: 0 # full history, so the base SHA exists locally
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
script:
# Assumes curl and jq are available in the image.
# NX_PIPELINES_READ_TOKEN is a placeholder name for a masked project
# access token with read access. Swap in CI_JOB_TOKEN only after you
# confirm your instance allows it to list pipelines.
- |
NX_BASE=$(curl --silent --fail \
--header "PRIVATE-TOKEN: ${NX_PIPELINES_READ_TOKEN}" \
"${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/pipelines?ref=${CI_DEFAULT_BRANCH}&status=success&order_by=id&sort=desc&per_page=1" \
| jq -r '.[0].sha // empty') || NX_BASE=""
# Fall back to the previous commit if the API call fails, returns
# nothing, or returns a SHA that is not in local history.
if [ -z "$NX_BASE" ] || ! git cat-file -e "${NX_BASE}^{commit}" 2>/dev/null; then
echo "No usable last-green SHA; falling back to HEAD~1"
NX_BASE=$(git rev-parse HEAD~1)
fi
echo "Nx base: $NX_BASE head: $CI_COMMIT_SHA"
npx nx affected -t lint test build --base="$NX_BASE" --head="$CI_COMMIT_SHA"
A default-branch job reads the SHA of the latest successful pipeline through the GitLab pipelines API with a read-only token. If no usable SHA comes back, it falls back to HEAD~1 before running nx affected.
Why does nx affected fail on shallow clones, and how do you fix it?
GitLab runners clone shallowly unless told otherwise. The depth comes from the project's CI/CD settings or the GIT_DEPTH variable. The runner also fetches only the ref being built, so the target branch may not exist locally. nx affected runs a git merge-base between --base and --head, which needs both commits and enough history to connect them. If the base SHA falls outside the fetched window, git fails with an unknown revision or no-merge-base error. If the commit exists but the shared ancestor is cut off, the diff can come out wrong. You may see every project flagged as affected, or a merge base that isn't the true fork point.
Fix 1: full history for one job
Set GIT_DEPTH: 0 only on the job that computes affected projects. Other jobs keep the fast default. This is the simplest fix and works the same for every pipeline type. The cost is clone time and disk use, which grow with the repository's history.
Fix 2: targeted fetch
Keep the shallow clone and fetch only what the diff needs. In merge request pipelines, that means CI_MERGE_REQUEST_TARGET_BRANCH_NAME. On the default branch, it means the tracked base SHA. Fetching a single commit at depth 1 is not enough on its own. You need to deepen or fetch a range until the merge base is reachable, which adds script logic and retry cases.
| Factor | GIT_DEPTH: 0 |
Targeted fetch |
|---|---|---|
| Clone time | Grows with history | Close to shallow |
| Runner disk | Full object store | Small |
| Script complexity | One variable | Fetch and deepen logic |
| Edge cases | Few | Long-lived branches, force-pushed or garbage-collected bases |
Illustrative estimate: assume a 2 GB full history and a 150 MB shallow checkout. Fix 1 then costs roughly an extra 1.85 GB of transfer per affected job, while Fix 2 stays near 150 MB plus the fetched range.
affected:full:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
GIT_DEPTH: "0" # full clone here only; other jobs keep the shallow default
script:
# Runner fetches only the built ref, so bring in the target branch explicitly
- git fetch origin "+refs/heads/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME:refs/remotes/origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
- npx nx affected -t lint test build --base="origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --head=HEAD
affected:targeted:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
GIT_DEPTH: "20"
script:
- TARGET="$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
- TARGET_REF="+refs/heads/$TARGET:refs/remotes/origin/$TARGET"
- SOURCE_REF="refs/merge-requests/$CI_MERGE_REQUEST_IID/head"
- git fetch --depth=50 origin "$TARGET_REF"
- |
# Deepen in steps; stop as soon as git can connect the two histories
for i in 1 2 3 4 5; do
git merge-base "origin/$TARGET" HEAD >/dev/null 2>&1 && break
git fetch --deepen=200 origin "$TARGET_REF" "$SOURCE_REF"
done
# Last resort for long-lived branches: give up on shallow and fetch everything
if ! git merge-base "origin/$TARGET" HEAD >/dev/null 2>&1; then
echo "No merge base after deepening; unshallowing"
git fetch --unshallow origin "$TARGET_REF" "$SOURCE_REF"
fi
- npx nx affected -t lint test build --base="origin/$TARGET" --head=HEAD
Two GitLab CI jobs for merge request pipelines: one sets GIT_DEPTH to 0 only for the affected job, the other keeps a shallow clone and deepens the target and merge request refs until git merge-base succeeds, falling back to --unshallow.
A complete .gitlab-ci.yml for Nx affected pipelines
The configuration has three layers, each with a specific job.
Workflow rules
Without workflow:rules, pushing to a branch with an open merge request starts two pipelines: a branch pipeline and an MR pipeline. Use GitLab's standard pattern. Run when CI_PIPELINE_SOURCE is merge_request_event. Skip branch pipelines when CI_COMMIT_BRANCH is set and CI_OPEN_MERGE_REQUESTS is non-empty. Otherwise run branch pipelines. This gives exactly one pipeline per push. That matters because each pipeline resolves its own $BASE.
Setup and affected jobs
A setup job runs npm ci once and computes BASE and HEAD. It passes them downstream through a dotenv report artifact. Each affected job then runs npx nx affected -t lint test build --base=$BASE --head=$HEAD.
To split the work, create one job per target: affected-lint, affected-test and affected-build, each with a single -t. They run in parallel within the same stage.
The trade-off is cost. Every parallel job pays for its own dependency restore and cache download. Illustrative estimate: assume 90 seconds of install and cache overhead per job and 6 minutes of total target work.
- One job: about 7.5 minutes of wall-clock time and 7.5 runner minutes.
- Three jobs: about 3.5 minutes of wall-clock time, assuming evenly divided targets, but about 10.5 runner minutes.
Split when developer wait time costs more than runner minutes.
Forcing a full run
By default, Nx does not treat .gitlab-ci.yml or shared scripts outside project roots as project inputs, so nx affected ignores changes to them. Add a job with rules:changes that matches CI config and root tooling files. That job should run npx nx run-many -t lint test build instead of nx affected.
Should you use GitLab cache or artifacts for Nx outputs?
GitLab gives you two mechanisms for keeping files between jobs, and they solve different problems. Treat the package manager cache and the Nx cache as separate entries.
Key the package manager cache on the lockfile with cache:key:files, so a dependency change produces a fresh key instead of reusing a stale node_modules or store. The Nx local cache needs its own entry. Don't hardcode its path. Check cacheDirectory in nx.json, or the workspace default if that field is unset, because the default location has changed across Nx releases.
| Aspect | cache |
artifacts |
|---|---|---|
| Delivery guarantee | Best-effort; a miss is normal | Reliably passed to later stages |
| Scope | Keyed; may be runner-local without a distributed backend | Tied to the pipeline that produced it |
| Best for | Cross-pipeline acceleration | Build outputs that deploy jobs consume |
Use artifacts for anything a downstream job must have, such as the dist output a deploy job ships. Use cache only to speed things up.
Every job must still pass on a cold cache. If a job breaks when the cache is empty, it has a hidden dependency on a previous run.
Measure cache size as well. Uploading and downloading a large archive on every job can cost more time than the cache saves.
Correctness depends on your inputs and namedInputs. If a file or environment variable that affects output isn't declared, Nx computes the same hash after it changes and replays a stale result.
When the hash matches, Nx restores logs and outputs instead of rerunning tests and builds, which shortens feedback on large workspaces. It saves nothing on first runs, after dependency bumps, or for projects that change on every commit.
How do you verify which projects nx affected selects?
Before trusting affected selection to gate merges, make it visible. Add a lightweight debug job in an early stage that echoes the resolved NX_BASE and NX_HEAD values, then runs nx show projects --affected with the same --base and --head arguments your real jobs use. Passing the identical values matters. If the debug job recomputes the SHAs differently, it can report a clean result while the test job runs against a different range. Keep the job's output in the job log so reviewers can see why a pipeline skipped something.
Then exercise it with deliberate test branches:
| Change | Expected affected set | What a wrong result usually means |
|---|---|---|
Edit a Markdown file under docs/ |
Empty, unless a docs project owns that path | The file sits under a project root or is matched by a shared named input |
| Edit a shared library | The library plus every project that depends on it, directly or transitively | A missing import or an undeclared dependency in the project graph |
| Bump a package in the lockfile | Projects that use the changed packages, or every project if root files are part of shared inputs | The base SHA is wrong, or lockfile analysis is coarser than you assumed |
If any row surprises you, fix the graph or the base SHA before relying on the pipeline.
Affected-based pipelines are not always worth it. In a small repository, a full run may finish faster than the effort spent debugging selection. In graphs with heavy implicit coupling, such as code generation, shared configuration or runtime-only dependencies, affected selection can quietly skip projects that break. Release builds usually need full verification regardless. The simpler alternatives are to always run everything and lean on the Nx cache, or to use GitLab rules:changes path filters for coarse, per-directory job selection.
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.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby 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.