How does nx affected work, and why is the base SHA the most important input?
nx affected answers one question: which projects could have changed between two commits? It takes a base and a head SHA, collects the files that differ between them, and maps each file to the project that owns it using the project graph. It then walks the graph in reverse to add every project that depends on a touched project. The result is the set of projects whose build, test or lint targets need to run. Everything else is skipped, or replayed from cache.
On Jenkins this is the main lever for keeping monorepo builds short. A change to one service's handler should not rebuild forty unrelated services. This suits backend and platform engineers who run Nx monorepos on self-hosted agents, where agent time is a shared, finite resource and there is no hosted service choosing commits for you.
The base SHA is the input that decides correctness, and a wrong base fails quietly:
- Base too recent. Changed projects fall outside the diff and are skipped. The pipeline goes green without testing the code that changed.
- Base too old. The diff covers months of history and nearly every project runs. The pipeline still passes but takes as long as a full build.
Nx raises no error in either case, so you only notice from build times or from bugs that escape.
The graph has its own blind spot. Nx only knows about files it can attribute to a project. Shell scripts, Docker build contexts, root-level config and shared environment files must be declared as implicit dependencies or as target inputs. If they are not, changes to them trigger nothing.
+-----------------+ +-----------------+
| base SHA | | head SHA |
| (Jenkins input)| | (this commit) |
+--------+--------+ +--------+--------+
| |
+-----------+--------------+
|
v
+------------------------+
| files changed between | base too recent -> skips changes
| base and head (diff) | base too old -> runs nearly all
+-----------+------------+ (no error either way)
|
v
+------------------------+ +-------------------------+
| project graph: |<-----| implicit deps / inputs |
| file -> owning project| | scripts, Docker ctx, |
+-----------+------------+ | root config, env files |
| +-------------------------+
v
+------------------------+
| reverse walk: add all |
| dependent projects |
+-----------+------------+
v v
+------------------+ +------------------+
| affected: run | | unaffected: skip |
| build/test/lint | | or replay cache |
+------------------+ +------------------+
nx affected diffs the base and head commits, maps changed files to projects through the project graph and any declared implicit dependencies, then adds dependents to get the affected set; a wrong base SHA changes that set without raising an error.
Which base SHA should a Jenkins build use for pull requests and main?
The base SHA decides which of those changes Nx sees at all, so it needs a fixed rule for each build type.
Pull request builds
Use the merge-base between the target branch and the PR head. That is the commit where the PR branched off, as reported by git merge-base against the target branch (exposed as CHANGE_TARGET in multibranch pipelines). Comparing against the tip of the target branch is wrong. If main has moved on, its new commits show up as differences, and Nx rebuilds projects the PR never touched. The merge-base limits the diff to what the PR author actually changed.
Main-branch builds
Use the last commit that passed CI on main. This makes each green build cover everything since the previous green build, however many commits arrived in between.
Why HEAD~1 fails
HEAD~1 assumes every build covers exactly one new commit, and Jenkins does not guarantee that. Suppose someone pushes three commits at once. The build compares HEAD against HEAD~1 and ignores the first two commits, so a library changed in commit one is never tested.
Failures cause the same problem. If build N fails and build N+1 diffs only against N, the projects that broke in N are no longer "affected" and are never rebuilt. The pipeline turns green while the breakage stays in place, and nothing in the output tells you work was skipped.
| Build type | Base | Head | Failure mode if wrong |
|---|---|---|---|
| Pull request | Merge-base of target branch and PR head | PR head commit | Diffing against target tip rebuilds unrelated projects |
| Main branch | Last commit that passed CI | Current commit | HEAD~1 skips multi-commit pushes and failed builds |
| Main, no green build yet | Root commit, or run all targets | Current commit | Missing base errors out or under-builds |
How do you give Jenkins agents enough git history for nx base sha calculation?
Nx computes affected projects by diffing the base against the head, and for pull requests the base is usually git merge-base origin/main HEAD. That command only works if both commits and their common ancestor exist in the agent's local repository. Jenkins checkouts often lack them. A shallow clone stops history after a set number of commits, so the fork point may not be present. A single-branch refspec fetches only the PR branch, so origin/main does not exist locally. In both cases Nx either errors or compares against the wrong commit, and the affected set is either too large or silently incomplete.
The fix is to fetch the target branch explicitly before Nx runs. You have two options:
- Full history. Run
git fetch --unshallow(or disable shallow clone in the checkout settings), then fetchmain. This is reliable for any branch age, but it is slow and disk-heavy on large monorepos, especially on ephemeral agents that start without a workspace. - Deeper shallow fetch. Fetch
mainand the PR branch with--depthset to a few hundred commits, or use--deepento extend an existing shallow clone. This is faster, but a long-lived branch that forked before the depth window will still have no common ancestor.
Whichever you choose, add a guard step: run git merge-base origin/main HEAD and fail the build if it exits non-zero. Failing explicitly is better than letting Nx fall back to an incorrect diff. You can also retry once with a deeper fetch before failing.
#!/usr/bin/env bash
# Runs in a Jenkins `sh` step before any Nx command.
set -euo pipefail
# CHANGE_TARGET is set by Jenkins multibranch for PR builds; default to main.
TARGET="${CHANGE_TARGET:-main}"
DEPTH=200
# Explicit refspec so origin/$TARGET exists even after a single-branch checkout.
git fetch --no-tags --depth="$DEPTH" origin \
"+refs/heads/${TARGET}:refs/remotes/origin/${TARGET}"
find_base() { git merge-base "origin/${TARGET}" HEAD 2>/dev/null; }
if ! BASE=$(find_base); then
# Retry once: extend the shallow history on both refs.
echo "No merge-base within ${DEPTH} commits, deepening..."
git fetch --no-tags --deepen=1000 origin \
"+refs/heads/${TARGET}:refs/remotes/origin/${TARGET}"
if ! BASE=$(find_base); then
# Last resort: full history, only if the repo is still shallow.
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
echo "Still no merge-base, fetching full history..."
git fetch --no-tags --unshallow origin
fi
# Fail loudly instead of letting Nx diff against the wrong commit.
BASE=$(find_base) || {
echo "ERROR: no merge-base between origin/${TARGET} and HEAD" >&2
exit 1
}
fi
fi
echo "Nx base: ${BASE}"
npx nx affected -t lint test build --base="$BASE" --head=HEAD
A Jenkins shell step that fetches the PR target branch with a bounded depth, deepens and then unshallows only if no merge-base is found, fails the build if one still cannot be computed, and passes the verified merge-base to nx affected.
How can you track the last successful SHA on self-hosted CI?
Neither Nx nor Jenkins records the last green commit on main for you. You have to store it yourself, and there are two practical places to keep it.
Option one: a git tag or ref. When a main build succeeds, the pipeline force-pushes a ref such as refs/tags/nx-last-green to that commit. Later builds fetch the ref and pass it as --base. Because the value lives in the repository, any agent or job can read it. The cost is that the agent needs credentials with push rights. Concurrency is also a problem. If build A (older commit) finishes after build B (newer commit), A moves the tag backwards, and the next run re-tests work that has already passed.
Option two: the previous successful Jenkins build. The Git plugin exposes the commit of the last successful build for the job as GIT_PREVIOUS_SUCCESSFUL_COMMIT. You can also look it up through currentBuild.previousSuccessfulBuild. This needs no push access, but the value is only as reliable as the job's build history. Clearing builds or recreating the job loses it.
| Concern | Git tag/ref | Previous successful build |
|---|---|---|
| Push credentials needed | Yes | No |
| Survives job deletion | Yes | No |
| Out-of-order risk | Tag can move backwards | Lower, but still possible |
| Visible to other jobs | Yes | Same job only |
With either option, handle a missing or unreachable value the same way. On the very first build there is no prior green commit, and after a force-push the old commit may no longer exist. In both cases, check that the commit is present with git cat-file -e. If it isn't, run every target instead of guessing a base.
To prevent out-of-order updates, serialize main with disableConcurrentBuilds(). If you need concurrent builds, only move the tag when git merge-base --is-ancestor <current-tag> HEAD succeeds, which confirms the new commit is a descendant of the current tag.
#!/usr/bin/env bash
# ci/nx-ci.sh. Call from the Jenkinsfile:
# sh './ci/nx-ci.sh run' on every build
# sh './ci/nx-ci.sh mark-green' in post { success { } }, main branch only
set -euo pipefail
TAG=refs/tags/nx-last-green
HEAD_SHA=$(git rev-parse HEAD)
TARGETS=(lint test build)
# Fetch the shared tag. On the first-ever build it does not exist yet, which is fine.
git fetch --no-tags origin "+${TAG}:${TAG}" 2>/dev/null || true
case "${1:-}" in
run)
# Prefer the repo-wide tag. Fall back to the Git plugin's per-job value.
BASE=$(git rev-parse -q --verify "${TAG}^{commit}" || echo "${GIT_PREVIOUS_SUCCESSFUL_COMMIT:-}")
# cat-file -e fails if the commit is missing locally (shallow clone, force-push).
if [ -n "$BASE" ] && git cat-file -e "${BASE}^{commit}" 2>/dev/null; then
npx nx affected -t "${TARGETS[@]}" --base="$BASE" --head="$HEAD_SHA"
else
echo "No usable last-green commit; running every target."
npx nx run-many -t "${TARGETS[@]}"
fi
;;
mark-green)
OLD=$(git rev-parse -q --verify "${TAG}^{commit}" || true)
# Never move the tag backwards. Advance only if the old green commit is an ancestor of HEAD.
if [ -n "$OLD" ] && ! git merge-base --is-ancestor "$OLD" "$HEAD_SHA"; then
echo "Tag already points at a newer commit ($OLD); leaving it."
exit 0
fi
# The lease rejects the push if another build moved the tag after our fetch.
# An empty OLD means the push succeeds only if the tag does not exist yet.
git push --force-with-lease="${TAG}:${OLD}" origin "${HEAD_SHA}:${TAG}"
;;
*) echo "usage: $0 run|mark-green" >&2; exit 2 ;;
esac
A Jenkins helper script that picks the Nx base from a last-green tag or GIT_PREVIOUS_SUCCESSFUL_COMMIT and falls back to a full run-many when no usable commit exists. It advances the tag only forward, using merge-base --is-ancestor and a force-with-lease push.
Implementing nx affected in a declarative Jenkinsfile
Start with a Resolve SHAs stage that computes base and head once and exports them as NX_BASE and NX_HEAD through an environment block or env assignment. Every later nx affected call then reads the same pair. Passing --base/--head on each command also works, but a single source of truth prevents one stage from silently comparing against a different commit than another.
Follow it with a Debug stage that echoes both SHAs and runs nx show projects --affected. When a build unexpectedly tests nothing, or tests everything, this log tells you whether the cause is the SHA or the project graph, without re-running the pipeline.
Then run nx affected -t lint, -t test and -t build as separate stages. A red test stage tells you what failed at a glance, and Jenkins' stage view shows timing per target.
Add a cron trigger, for example nightly on main, that runs nx run-many -t lint test build across all projects. A wrong base SHA does not fail the build. It skips projects. A scheduled full run is the only check that catches those skipped projects.
Parallelism
Set --parallel from the agent's resources, not its core count alone. Test runners with heavy memory use may need fewer slots than CPUs. You have two options:
- One agent with Nx
--parallel: Nx schedules tasks along the dependency graph and shares one cache. - Jenkins
parallelstages: targets run on separate executors, which gives you isolation and more total capacity.
Do not combine both on the same agent. Three parallel stages each running --parallel=4 means twelve processes competing for one machine, and the result is flaky, memory-starved tests.
// Jenkinsfile (declarative). Agent assumed: 8 vCPU / 16 GB, so 3 Nx slots for memory-heavy tests
pipeline {
agent { label 'linux-8cpu-16gb' }
// Nightly full run on main only; other branches get an empty schedule
triggers { cron(env.BRANCH_NAME == 'main' ? 'H 2 * * *' : '') }
stages {
stage('Resolve SHAs') {
steps {
script {
sh 'git fetch --no-tags origin main' // shallow clones often lack the base commit
env.NX_HEAD = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
// PRs compare against the merge-base with main; main compares against its previous commit
env.NX_BASE = env.BRANCH_NAME == 'main'
? sh(script: 'git rev-parse HEAD~1', returnStdout: true).trim()
: sh(script: 'git merge-base origin/main HEAD', returnStdout: true).trim()
}
}
}
stage('Debug') {
steps {
sh 'echo "NX_BASE=$NX_BASE NX_HEAD=$NX_HEAD"'
sh 'npx nx show projects --affected' // reads NX_BASE/NX_HEAD from the environment
}
}
// Separate stages so a red stage names the failing target. Nx --parallel only, no Jenkins parallel {}
stage('Lint') { when { not { triggeredBy 'TimerTrigger' } }
steps { sh 'npx nx affected -t lint --parallel=3' } }
stage('Test') { when { not { triggeredBy 'TimerTrigger' } }
steps { sh 'npx nx affected -t test --parallel=3' } }
stage('Build') { when { not { triggeredBy 'TimerTrigger' } }
steps { sh 'npx nx affected -t build --parallel=3' } }
// Safety net: a wrong base SHA skips projects silently, so check every project nightly
stage('Nightly full run') {
when { triggeredBy 'TimerTrigger' }
steps { sh 'npx nx run-many -t lint test build --parallel=3' }
}
}
}
A declarative Jenkinsfile that resolves NX_BASE and NX_HEAD once, logs them with nx show projects --affected, runs lint, test and build as separate affected stages sized with --parallel on a single agent, and adds a nightly cron-triggered run-many as a safety net.
How do you persist Nx local and remote caches on Jenkins agents?
Nx writes task outputs and terminal logs to a cache directory inside the workspace. Current releases use .nx/cache, and you can change the location with cacheDirectory in nx.json or the NX_CACHE_DIRECTORY environment variable. An ephemeral agent or fresh container starts with an empty workspace, so every build runs cold.
On long-lived agents, point NX_CACHE_DIRECTORY at a mounted volume outside the job workspace so the cache survives workspace cleanup. This has two costs:
- Disk growth. The cache grows without limit until something prunes it.
- Concurrent writes. Parallel jobs on one agent write to the same directory. Give each executor its own directory, or accept that concurrent writers may collide.
A shared remote cache, backed by storage you operate, lets every agent reuse every other agent's work. A hit is only safe when the task's declared inputs fully describe what affects its output. If a build depends on an environment variable or a tool version, declare it in inputs using { "env": "VAR" } or { "runtime": "node --version" }. Otherwise two agents with different toolchains will share artifacts they should not share.
Cache poisoning is the main risk. If any job can write, a pull request from an untrusted branch can upload a tampered artifact that main later restores. Give write credentials only to builds of the main branch, and give pull request builds read-only access.
Owning the backend also makes you responsible for retention, eviction, encryption and access control.
Do not assume hits are happening. Nx labels each restored task [local cache] or [remote cache]. It also ends with a summary of how many tasks were read from cache. Check both in the Jenkins console log.
When should you avoid nx affected on Jenkins, and what are the alternatives?
Affected adds risk or little benefit in three situations:
- Small repos. If a full build finishes in a few minutes, the time saved does not justify debugging base SHA logic.
- Heavy implicit dependencies. If generated code, shared scripts or environment files are not declared in the project graph, Nx cannot see the link, and affected skips projects that actually broke.
- Frequent changes to root config or the lockfile. Changes to
package.json, the lockfile or the rootnx.jsonusually mark every project as affected. If these happen most weeks, many builds are full runs anyway.
| Approach | Fits when | Main risk | Engineering cost |
|---|---|---|---|
nx affected |
Large graph, accurate dependencies | Wrong base SHA or undeclared inputs | Moderate: SHA tracking, fetch depth |
| Full build every time | Small or fast repos | Slow feedback as the repo grows | Lowest |
| Path-based Jenkins triggers | Few, clearly separated directories | Path rules drift from real dependencies | Low at first, grows with every new project |
| Per-project pipelines | Teams that deploy independently | Duplicated config, cross-project breakage missed | High: many Jenkinsfiles to maintain |
Illustrative estimate. Assume 50 projects, an average of 2 minutes per project on 5 parallel executors, and a typical PR that affects 8 projects:
- Typical PR: about 4 minutes.
- A lockfile bump or a change to a shared library: all 50 projects, about 20 minutes.
The average looks cheap, but the worst case still happens often. Size agent pools and timeouts for the full run, not the typical one. Otherwise queues back up at exactly the moment a shared dependency changes.
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 jenkins, 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.