What is Nx Release for Docker images and how does it work?
Nx Release treats a deployable service the way it treats a library: as a project that produces a versioned artifact. For a library that artifact is a package. For a service it is a container image. The image gets its own version, derived from the commits that touched the service, and that version is the tag you deploy. This separates "what changed" from "what is running." You can always trace a running container back to a version, a changelog entry and a git tag.
Nx Release runs in three phases, and each one maps onto the image lifecycle:
- Version decides the next version for each affected project, usually from conventional commits, and writes it where Nx expects it.
- Changelog records what changed, commits the result and creates the git tag.
- Publish runs each project's publish target. For a service, that target builds the image, applies the version tag and pushes it to the registry.
The full path looks like this:
commits -> version -> changelog -> git tag -> docker build -> tag -> push -> deploy by tag or digest
Running nx release executes all three phases. While you are debugging, run them one at a time with nx release version, nx release changelog and nx release publish, and add --dry-run to preview the computed versions and changelog text without writing files, tagging or pushing. Subcommands, flags and Docker-specific options have changed between Nx releases, so confirm them against the documentation for your installed Nx version before scripting anything.
#!/usr/bin/env bash
# Debug Nx Release for one service image, one phase at a time.
# Confirm subcommands and flags with `npx nx release --help` for your installed Nx version.
set -euo pipefail
SERVICE="api" # placeholder: the Nx project that builds the image
# 0. Preview the whole pipeline (version -> changelog -> publish).
# Nothing is written, committed, tagged or pushed.
npx nx release --projects="$SERVICE" --dry-run --verbose
# 1. Version: compute the next version from commits that touched the service.
# The dry run prints the computed version without writing it.
npx nx release version --projects="$SERVICE" --dry-run --verbose
# 2. Changelog: preview the entry, the release commit and the git tag.
# Check `npx nx release changelog --help`. Depending on your Nx version and
# config, this subcommand may expect the version as a positional argument.
npx nx release changelog --help
# 3. Publish: runs the project's publish target, which builds, tags and pushes
# the image. The dry run must not push to the registry.
npx nx release publish --projects="$SERVICE" --dry-run --verbose
# After a real (non-dry) release, check that the git tag exists for the service.
# The tag pattern depends on your releaseTagPattern setting.
git tag --list "*${SERVICE}*" --sort=-creatordate | head -n 5
# Resolve the pushed tag to a digest so you can deploy by digest.
# Placeholder image reference:
# docker buildx imagetools inspect registry.example.com/acme/api:1.4.0
A debugging script that previews a full Nx Release for one service with --dry-run, steps through the version and publish phases separately, points to the help text for the changelog phase's arguments, and then checks the resulting git tag and image digest.
Who should use it, and when should you avoid it?
The best fit is a platform or backend team running several deployable services in one Nx monorepo. These teams usually have a pile of CI scripts that read the last tag, bump a version, write a changelog, and push an image. Each service ends up with a slightly different script. Nx Release replaces all of that with one flow driven by the project graph. Because Nx already knows which projects a commit touched, it versions and publishes only those services. Engineers stop maintaining bash that parses git log and stop debugging why one service's tag drifted from the others. The time saved is mostly the upkeep of that tooling, and the incidents it causes when someone edits it without understanding it.
It is the wrong tool in several cases:
- A single service. A short script or a standard CI action is simpler, and the release config would be overhead with no graph to exploit.
- A repo that is not a real Nx workspace. Without a project graph, Nx cannot work out which services are affected.
- An organization that forbids CI from pushing commits or tags to git. The default flow depends on that write access.
- Teams that won't keep commit messages disciplined. Version bumps and changelogs inferred from conventional commits become wrong without that discipline.
The costs are ongoing. Release groups and per-project settings need upkeep as services are added or split. Commit conventions need enforcement, usually through a lint hook and review. Nx upgrades can change release behavior, so treat each upgrade as a change to your deployment pipeline and run a dry run before you merge it.
Should services use semantic versioning or date- and SHA-based tags?
The tag scheme should match how consumers refer to your image. Semantic versioning is a contract: a major bump says "something you depend on changed incompatibly." That is useful when other teams, customers or Helm charts pin to 2.x and need to know whether an upgrade is safe. A public API gateway, a shared auth service or an image other organizations pull all fit this model.
Many internal services have no such consumers. They are deployed from main several times a day, and the only thing that references the tag is your own deployment manifest, updated by automation. In that setting "breaking" has no clear meaning, because database migrations and API changes are coordinated through feature flags and staged rollouts, not version numbers. Semver then becomes ceremony. Engineers still have to write feat!: or BREAKING CHANGE footers correctly, reviewers still have to police them, and nobody reads the resulting major version. You pay for the commit discipline and get little back.
| Scheme | Example tag | Best fit | Main cost |
|---|---|---|---|
| Semantic version | 3.4.1 |
Services with external or cross-team API consumers | Requires accurate commit classification |
| Calendar-based | 2026.11.17.2 |
Continuously deployed internal services | Says nothing about compatibility |
| Build/SHA-based | sha-9f2c1ab |
Any service, as a traceability tag | Not human-orderable |
These schemes are not mutually exclusive. A common pattern publishes a semver or date tag for people and a SHA tag for machines, so every image traces back to an exact commit regardless of the primary scheme.
How do you configure release groups, independent versioning and conventional commits?
Release configuration lives under the release key in nx.json. Each entry in release.groups names a set of projects, matched by name, glob or tag. The group's projectsRelationship decides whether its members share one version (fixed) or version separately (independent). For deployable services, use independent with a tag pattern such as {projectName}@{version}. Each service then gets its own git tag history, and the image tag can be derived from that git tag.
With conventionalCommits enabled, the commit type sets the bump: fix gives a patch, feat gives a minor, and a ! or BREAKING CHANGE footer gives a major. Nx decides which projects a commit belongs to by the files it touches. Keep scopes aligned with project names so the changelogs and the file-based attribution tell the same story.
When a shared library changes, the release fans out to every dependent service. Independent versioning plus affected detection keeps that fan-out bounded. A service with no changed files and no changed dependencies gets no bump, no tag and no new image.
The trade-offs are real:
- Squash merges take the PR title as the commit message. A title like "updates" with no conventional type produces no bump, or the wrong one. Lint PR titles before merge.
- Library fan-out is noisy. A one-line utility fix can produce many images, which means more build minutes and more registry storage.
- Affected detection only sees the files you declare. A changed base image upstream, or a Dockerfile that copies files outside the project, can slip past it. Add the Dockerfile and any copied paths to the project's
inputs.
Base-image CVEs aren't commits at all, so they need their own path. Keep a separate security-rebuild job that rebuilds the current releases on a fresh base and publishes them under a distinct tag.
// nx.json (Nx parses this file as JSONC, so comments are allowed)
{
"release": {
"groups": {
// Deployable services: each one gets its own version and git tag history
"services": {
"projects": ["tag:type:service"],
"projectsRelationship": "independent",
// Produces tags like orders-api@1.4.2; CI derives the image tag from this
"releaseTagPattern": "{projectName}@{version}"
},
// Shared libraries version together; a bump here fans out to dependent services
"libs": {
"projects": ["tag:type:lib"],
"projectsRelationship": "fixed",
"releaseTagPattern": "libs@{version}"
}
},
// fix -> patch, feat -> minor, feat! or BREAKING CHANGE footer -> major
"version": { "conventionalCommits": true },
"changelog": { "projectChangelogs": true }
},
"namedInputs": {
// Files the Docker build reads that affected detection would otherwise miss
"dockerInputs": [
"{projectRoot}/Dockerfile",
"{projectRoot}/.dockerignore",
"{workspaceRoot}/docker/base.Dockerfile"
]
},
"targetDefaults": {
"docker-build": {
// Own sources, dependency sources (^default), plus the declared Docker files
"inputs": ["default", "^default", "dockerInputs"]
}
}
}
An nx.json with an independent services group that uses per-project tags, a fixed library group, conventional-commit bumps, and Dockerfile paths declared as inputs so affected detection sees them.
How should you tag and label images so every release is immutable and traceable?
Every pushed image gets exactly one immutable version tag, such as orders-api:1.4.2, and that tag is never pushed again. A security rebuild therefore ships as 1.4.3, not as an overwrite. Adding a git-SHA tag like orders-api:sha-3f9c2e1 is optional but cheap, and it answers "which commit is this?" without a lookup. Moving tags such as 1, 1.4, staging and latest are convenience pointers for humans and dev environments only.
| Tag type | Example | Mutable | Use for |
|---|---|---|---|
| Version | 1.4.2 |
No | Deployments, rollbacks |
| Git SHA | sha-3f9c2e1 |
No | Tracing to source |
| Major / minor | 1, 1.4 |
Yes | Local pulls, docs |
| Channel | staging, latest |
Yes | Dev convenience |
| Digest | @sha256:… |
No | Pinning exact bytes |
Deployments should reference the version tag or the digest. A moving tag makes a manifest ambiguous: orders-api:1.4 means different images on different days. Nodes that cached an older pull may run something other than what the registry now serves, and a rollback to 1.4 rolls back to nothing in particular. Digests are the strongest guarantee, but nobody can read them in a diff. A common compromise is orders-api:1.4.2@sha256:…, which pins the exact image and keeps a readable tag beside it.
Keep the version in the git tag (for example orders-api@1.4.2) the same as the image tag. A running container's tag then leads directly to the commit and its changelog entry. For the same reason, bake the version into the image itself. Pass VERSION, GIT_SHA and REPO_URL as build args and write them to org.opencontainers.image.version, org.opencontainers.image.revision and org.opencontainers.image.source. With those labels set, docker inspect on a running container tells you exactly what it is, even if someone has retagged the image.
#!/usr/bin/env bash
# Dockerfile excerpt that consumes the build args:
# ARG VERSION
# ARG GIT_SHA
# ARG REPO_URL
# LABEL org.opencontainers.image.version=$VERSION \
# org.opencontainers.image.revision=$GIT_SHA \
# org.opencontainers.image.source=$REPO_URL
set -euo pipefail
IMAGE=registry.example.com/acme/orders-api
VERSION=1.4.2 # same as git tag orders-api@1.4.2
GIT_SHA=$(git rev-parse HEAD)
SHORT_SHA=$(git rev-parse --short=7 HEAD)
REPO_URL=
# Refuse to overwrite an immutable version tag; a rebuild must bump the version.
if docker manifest inspect "$IMAGE:$VERSION" >/dev/null 2>&1; then
echo "$IMAGE:$VERSION already exists; release a new version instead" >&2
exit 1
fi
docker build \
--build-arg VERSION="$VERSION" \
--build-arg GIT_SHA="$GIT_SHA" \
--build-arg REPO_URL="$REPO_URL" \
-t "$IMAGE:$VERSION" \
-t "$IMAGE:sha-$SHORT_SHA" \
apps/orders-api
docker push "$IMAGE:$VERSION"
docker push "$IMAGE:sha-$SHORT_SHA"
# Moving tags (1, 1.4) are convenience pointers only; never deploy them.
docker tag "$IMAGE:$VERSION" "$IMAGE:1.4" && docker push "$IMAGE:1.4"
# Emit the reference deployments should use: readable tag plus pinned digest.
DIGEST=$(docker inspect --format '{{index .RepoDigests 0}}' "$IMAGE:$VERSION" | cut -d@ -f2)
echo "deploy: $IMAGE:$VERSION@$DIGEST"
A release script that passes version, revision and source as build args into OCI labels, pushes an immutable version tag and a git-SHA tag, refuses to overwrite an existing version, and prints a tag-plus-digest reference for deployments.
How do you wire Docker build and push into the publish step?
Nx gives you two ways to get from "version computed" to "image pushed."
Built-in Docker release support. Recent Nx releases have added first-party Docker handling to nx release, which can build and tag images as part of the release. This support has been evolving, so the plugin name, config keys and default tag formats may differ between versions. Check the docs for the Nx version in your lockfile before you copy any configuration.
A custom publish target. nx release publish runs each project's nx-release-publish target. You define that target yourself, as a script that does the following:
- Reads the version the versioning step produced. Use the project's version file or the per-project results from the programmatic release API.
- Passes that version to
docker buildas a build arg, so the Dockerfile writes it into theorg.opencontainers.image.versionlabel. - Tags the image and pushes it.
| Built-in support | Custom publish target | |
|---|---|---|
| Setup effort | Low | Moderate |
| Stability across Nx upgrades | Config may change | Depends only on the target contract |
| Control over tags, args, checks | Limited to exposed options | Full |
| Maintenance owner | Nx | Your team |
Whichever path you choose, authenticate to the registry before the release starts. Use docker login --password-stdin with a short-lived CI credential, or OIDC if your registry supports it. If you authenticate during the release, a bad credential can stop it halfway, leaving git tags pushed but no images.
Also refuse to overwrite existing tags. Before you push, query the registry for the tag (for example with docker manifest inspect) and fail if it already exists. Turn on tag immutability in the registry as a second safeguard.
#!/usr/bin/env bash
# publish-image.sh <project-root> <image-repo>
# Called by a project's nx-release-publish target, after `nx release version` has run.
# Assumes `docker login` already happened earlier in the CI job, before the release began.
set -euo pipefail
PROJECT_ROOT="$1" # e.g. apps/billing-api
IMAGE_REPO="$2" # e.g. registry.example.com/acme/billing-api
# Read the version the versioning step wrote to the project's version file.
VERSION="$(jq -r '.version' "${PROJECT_ROOT}/package.json")"
if [[ -z "${VERSION}" || "${VERSION}" == "null" ]]; then
echo "No version found in ${PROJECT_ROOT}/package.json" >&2
exit 1
fi
IMAGE="${IMAGE_REPO}:${VERSION}"
# Do not overwrite a released tag. A successful inspect means the tag already exists.
# Inspect also fails on auth or network errors, so a nonzero exit is not proof the tag is free.
# Registry-side tag immutability remains the real safeguard.
if docker manifest inspect "${IMAGE}" > /dev/null 2>&1; then
echo "Refusing to overwrite existing tag ${IMAGE}" >&2
exit 1
fi
# Pass the version as a build arg. The Dockerfile should declare:
# ARG APP_VERSION
# LABEL org.opencontainers.image.version=$APP_VERSION
docker build \
--file "${PROJECT_ROOT}/Dockerfile" \
--build-arg "APP_VERSION=${VERSION}" \
--tag "${IMAGE}" \
.
docker push "${IMAGE}"
echo "Pushed ${IMAGE}"
This script can back a project's nx-release-publish target: it reads the computed version, refuses to push if that tag already exists in the registry, passes the version into the OCI version label as a build arg, and then pushes the image.
How do you run releases safely in CI and roll back?
Run the same release command in two modes. On pull requests, run nx release --dry-run so reviewers can see the projected version bumps and changelog entries without writing anything. On main, run the real release in a dedicated job. This job is the only place that may commit, tag, and push images.
That job needs credentials that can push commits and tags to main. Protected branches usually block this, so grant a narrow exception to the release bot identity rather than relaxing protection for everyone. The release commit will trigger your pipeline again, so skip release jobs when the author is the bot or when the commit message matches your release-commit pattern. Otherwise you get a release loop.
Serialize release jobs with a CI concurrency group or lock. If two merges land close together and both compute "next version" from the same base, they will collide.
Publishing can fail partway, for example when the git tag is pushed but one image push fails. Treat git tags as the source of truth for what was released, and make publish idempotent. On retry, skip any image whose tag already resolves to the expected digest and push only what is missing. Never bump the version again to get past a failure.
Rollback means redeploying a previous immutable tag or, better, its digest. It is not a re-release.
There are lighter alternatives:
- Tag-only releases skip the version commit.
- Computing versions in CI without committing keeps the repository clean.
- Other monorepo release tools follow similar models.
Each of these trades away some traceability. You may lose the in-repo changelog, versions recorded in project files, or a single commit that ties a version to its source.
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 release docker images, 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.