Nx Release - Affected Logic

[marc-wilson]

Current Behavior

In a multi-app monorepo, nx release (version/publish) appears to assume all releaseable projects were built, which conflicts with Nx’s “affected” workflow. This effectively forces a choice between using affected or using release.

Example CI (simplified)

- run: npx nx affected -t lint,test,build,docker:build
- run: npx nx release version --dockerVersion=${{ github.sha }}
- run: npx nx release publish

On every PR, we only build affected apps/targets (great!).
But nx release publish then tries to publish everything in the release group, implicitly assuming every project has its artifact ready (e.g., container images), which breaks the affected pattern.

---

Expected behavior

• A way for nx release to respect the affected graph, or
• First-class flags/inputs so version/publish can target only affected projects (or a provided subset) without custom scripting.

Examples:

nx release version --projects $(npx nx show projects --affected)
nx release publish --projects $(npx nx show projects --affected)

Or even a native --affected flag for nx release version/publish.

---

Actual behavior

• nx release publish considers all projects in the release group (or repo), which assumes non-affected projects were also built and are ready to publish.
• This conflicts with the incremental/affected workflow that Nx promotes as a core feature.

---

Why this matters

Nx positions “affected” as a core productivity/value driver. When release requires publishing everything, pipelines either:

1. Abandon “affected” and build everything every time (slow, costly), or
2. Add custom glue code around nx release to filter projects (more complexity).

This breaks one of Nx’s biggest selling points—incremental builds and deploys.

---

Minimal reproduction (conceptual)

1. Monorepo with multiple publishable apps/packages (each with docker:build and a release group).
2. Change one app.
3. Run:

   npx nx affected -t docker:build
   npx nx release version
   npx nx release publish

4. Observe publish attempts to release all projects, not just the affected/built ones.

The docker example uses run-many which isn't a good idea because my repo is quite large.

name: Docker Publish

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build applications
        run: npx nx run-many -t build

      - name: Login to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_TOKEN }}

      - name: Build and tag Docker images
        run: npx nx release version --dockerVersionScheme=production

      - name: Publish Docker images
        run: npx nx release publish

There's this one which doesn't build anything at all. so not really a realistic example

name: Publish

on:
  push:
    tags:
      - v*.*.*

jobs:
  test:
    name: Publish
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # needed for provenance data generation
    timeout-minutes: 10
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          filter: tree:0

      - name: Install Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org/

      - name: Install dependencies
        run: npm install
        shell: bash

      - name: Print Environment Info
        run: npx nx report
        shell: bash

      - name: Publish packages
        run: npx nx release publish
        shell: bash
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }}
          NPM_CONFIG_PROVENANCE: true

Expected Behavior

nx release should not try and publish things that aren't affected or provide some --affected flag.

GitHub Repo

No response

Steps to Reproduce

1. Create a monorepo
2. Make one of your libs or apps with a docker container "releasable"
3. Put together a GitHub pipeline that only releases your "releasable" app when it has been affected

Nx Report

Node           : 22.12.0
OS             : darwin-arm64
Native Target  : aarch64-macos
pnpm           : 10.19.0

nx                     : 22.0.1
@nx/js                 : 22.0.1
@nx/jest               : 22.0.1
@nx/eslint             : 22.0.1
@nx/workspace          : 22.0.1
@nx/devkit             : 22.0.1
@nx/esbuild            : 22.0.1
@nx/eslint-plugin      : 22.0.1
@nx/module-federation  : 22.0.1
@nx/nest               : 22.0.1
@nx/next               : 22.0.1
@nx/node               : 22.0.1
@nx/plugin             : 22.0.1
@nx/react              : 22.0.1
@nx/rollup             : 22.0.1
@nx/vite               : 22.0.1
@nx/web                : 22.0.1
@nx/webpack            : 22.0.1
@nx/docker             : 22.0.1
typescript             : 5.9.3
---------------------------------------
Registered Plugins:
@nx/js/typescript
@nx/next/plugin
@nx/jest/plugin
@nx/eslint/plugin
@nx/docker
@nx/vite/plugin
@nx/webpack/plugin
@nx/js/typescript

Failure Logs

Package Manager Version

No response

Operating System

• macOS
• Linux
• Windows
• Other (Please specify)

Additional Information

No response

[AndriiTsok]

Hi @marc-wilson I experienced the same issue with releasing independent applications via @nx/docker plugin. Recent changes to the plugin seems introduced some regression issues.

1. The plugin was picking up non-docker projects to be processed as docker ones.
2. The plugin was trying to publish projects that were not released/versioned.

I opened #33288 with a few fixes that should resolve this issue.

[marc-wilson]

Thanks @AndriiTsok. Looking forward to testing out your fix. But, I don't think this is specific to docker. I may not be 100% clear on how release groups work but what if I had other releasable (non-docker) things like libs? Wouldn't it be the same issue?

Is the intent with release groups to build things together and release them group-by-group?

ie: (probably the wrong syntax)

nx affected -t build,docker:build
nx release groupa
nx release docker-group

or, should nx release handle the release of all groups?

I am expecting that nx release first looks as what's affected, then releases anything that was affected which has a configured release target. basically the same behavior of adding a random target somewhere in one of the apps project.json. If you add my-target you can run nx affected -t my-target and it would do what you would expect. So, just really confused on why release doesn't behave like this.

[Coly010]

Nx Release behaves somewhat differently to Nx as a task runner.
Nx Release uses the config you have defined in your nx.json to determine the state of how things should be released.

Release Groups are used to configure which projects should be released together. Meaning that running nx release publish would publish everything within the group.
Setting projectsRelationship to independent also only impacts how these projects are versioned and how their changelogs are generated. When set to independent the projects within the group will maintain their own version, when set to fixed, the projects will share the same version number.

You have options available to finetune your release process acutely to your needs.
You could do something such as: nx release version --projects $(npx nx show projects --affected) as was mentioned, or you can use the Nx Release Programmatic API to build a release script: https://nx.dev/docs/guides/nx-release/programmatic-api
The release script can be used to help finetune what projects are versioned and what are published based on your own criteria as it is just JavaScript code.

Finally, Release Groups offer a groupPreVersionCommand that can be used to ensure the artifacts are ready for publishing. This command can be focused on just the packages within the group:

"groupPreVersionCommand": "nx run-many -t build -p project-a,project-b"

Alternatively, something that we do on one of our repos is to have the CI workflow set an ENV var that we use in the preVersionCommand: "preVersionCommand": "nx run-many -t build -p $PROJECTS_TO_RELEASE"
Then our nx release command becomes something akin to nx release --projects $PROJECTS_TO_RELEASE

[marc-wilson]

Thanks @Coly010 for the detailed explanation — this helps clarify the intent behind nx release and release groups.

That said, I think this still highlights a fundamental DX and conceptual gap between Nx’s “affected” model (which is central to its value) and how nx release behaves today.

---

On affected vs. release

It’s surprising that nx release diverges so significantly from Nx’s standard affected-graph behavior.
The entire Nx ecosystem is built around incremental workflows — running tasks only for changed projects — so it feels counterintuitive that nx release ignores this core principle.

Moving project-specific behavior into global configuration (via nx.json) also feels inconsistent with the rest of Nx, where project-level configuration lives in project.json. This makes release feel like a different system layered on top of Nx rather than part of it.

---

On release groups

The explanation around release groups makes sense conceptually, but it doesn’t map well to most CI/CD use cases.
Releasing without an associated build doesn’t reflect how teams typically work — especially when using affected workflows. In practice, a release almost always follows a build step like:

1. Implement feature/fix
2. Open PR
3. Run CI (with nx affected -t lint,test,build)
4. On merge → Release the affected apps/packages

So, in this flow, nx release ends up rebuilding (sometimes re-releasing) unaffected projects — defeating the purpose of incremental builds and introducing unnecessary complexity or cost.

---

On groupPreVersionCommand

While groupPreVersionCommand offers some flexibility, it doesn’t fully address the issue.
Running a second build pass — potentially across unaffected projects — isn’t ideal. It would be much more natural if nx release could directly respect the affected graph or accept a flag like --affected (or --projects $(npx nx show projects --affected)).

---

Overall

Respectfully, I still believe this is a gap or bug in behavior rather than an intentional design difference.
For teams that rely on Nx’s incremental CI/CD patterns, it feels wrong to have to choose between “use affected” and “use release.”

Bringing nx release in line with Nx’s core affected-graph logic would make releases far more consistent, efficient, and intuitive — especially for large monorepos.