Publish in CI/CD

Nx Release makes it easy to move your publishing process into your CI/CD pipeline across different package ecosystems.

General Concepts

Automatically Skip Publishing Locally

When running nx release, after the version updates and changelog generation, you will be prompted with the following question:

nx release

1... 2? Do you want to publish these versions? (y/N) › 3

To move publishing into an automated pipeline, you will want to skip publishing when running nx release locally. To do this automatically, use the --skip-publish flag:

nx release --skip-publish

1... 2 3Skipped publishing packages. 4

Use the Publish Subcommand

Nx Release provides a publishing subcommand that performs just the publishing step. Use this in your CI/CD pipeline to publish the packages.

nx release publish

1NX Running target nx-release-publish for 3 projects: 2 3- pkg-1 4- pkg-2 5- pkg-3 6 7... 8

Publishing NPM Packages

Example NPM Publish Output

nx release publish

1NX Running target nx-release-publish for 3 projects: 2 3- pkg-1 4- pkg-2 5- pkg-3 6 7————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————— 8 9> nx run pkg-1:nx-release-publish 10 11 12📦 @myorg/pkg-1@0.0.2 13=== Tarball Contents === 14 15233B README.md 16277B package.json 1753B src/index.ts 1861B src/lib/pkg-1.ts 19=== Tarball Details === 20name: @myorg/pkg-1 21version: 0.0.2 22filename: testorg-pkg-1-0.0.2.tgz 23package size: 531 B 24unpacked size: 624 B 25shasum: {shasum} 26integrity: {integrity} 27total files: 12 28 29Published to https://registry.npmjs.org with tag "latest" 30 31> nx run pkg-2:nx-release-publish 32 33 34📦 @myorg/pkg-2@0.0.2 35=== Tarball Contents === 36 37233B README.md 38277B package.json 3953B src/index.ts 4061B src/lib/pkg-2.ts 41=== Tarball Details === 42name: @myorg/pkg-2 43version: 0.0.2 44filename: testorg-pkg-2-0.0.2.tgz 45package size: 531 B 46unpacked size: 624 B 47shasum: {shasum} 48integrity: {integrity} 49total files: 12 50 51Published to https://registry.npmjs.org with tag "latest" 52 53> nx run pkg-3:nx-release-publish 54 55 56📦 @myorg/pkg-3@0.0.2 57=== Tarball Contents === 58 59233B README.md 60277B package.json 6153B src/index.ts 6261B src/lib/pkg-3.ts 63=== Tarball Details === 64name: @myorg/pkg-3 65version: 0.0.2 66filename: testorg-pkg-3-0.0.2.tgz 67package size: 531 B 68unpacked size: 624 B 69shasum: {shasum} 70integrity: {integrity} 71total files: 12 72 73Published to https://registry.npmjs.org with tag "latest" 74 75————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————— 76 77NX Successfully ran target nx-release-publish for 3 projects 78

NPM Publishing in GitHub Actions

A common way to automate publishing NPM packages is via GitHub Actions. An example of a publish workflow is as follows:

1# ./.github/workflows/publish.yml 2name: Publish 3 4on: 5 push: 6 tags: 7 - v*.*.* 8 9jobs: 10 test: 11 name: Publish 12 runs-on: ubuntu-latest 13 permissions: 14 contents: read 15 id-token: write # needed for provenance data generation 16 timeout-minutes: 10 17 steps: 18 - name: Checkout repository 19 uses: actions/checkout@v4 20 with: 21 fetch-depth: 0 22 filter: tree:0 23 24 - name: Install Node 25 uses: actions/setup-node@v4 26 with: 27 node-version: 20 28 registry-url: https://registry.npmjs.org/ 29 30 - name: Install dependencies 31 run: npm install 32 shell: bash 33 34 - name: Print Environment Info 35 run: npx nx report 36 shell: bash 37 38 - name: Publish packages 39 run: npx nx release publish 40 shell: bash 41 env: 42 NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }} 43 NPM_CONFIG_PROVENANCE: true 44

This workflow will install node, install npm dependencies, then run nx release publish to publish the packages. It will run on every push to the repository that creates a tag that matches the pattern v*.*.*. A release process using this workflow is as follows:

  1. Run nx release --skip-publish locally. This will create a commit with the version and changelog updates, then create a tag for the new version.
  2. Push the changes (including the new tag) to the remote repository with git push && git push --tags.
  3. The publish workflow will automatically trigger and publish the packages to the npm registry.

Configure the NODE_AUTH_TOKEN

The NODE_AUTH_TOKEN environment variable is needed to authenticate with the npm registry. In the above workflow, it is passed into the Publish packages step via a GitHub Secret.

Generate a NODE_AUTH_TOKEN for NPM

To generate the correct NODE_AUTH_TOKEN for the npmJS registry specifically, first login to https://www.npmjs.com/. Select your profile icon, then navigate to "Access Tokens". Generate a new Granular Access Token. Ensure that the token has read and write access to both the packages you are publishing and their organization (if applicable). Copy the generated token and add it as a secret to your GitHub repository.

Add the NODE_AUTH_TOKEN to GitHub Secrets

To add the token as a secret to your GitHub repository, navigate to your repository, then select "Settings" > "Secrets and Variables" > "Actions". Add a new Repository Secret with the name NPM_ACCESS_TOKEN and the value of the token you generated in the previous step.

Note: The NPM_ACCESS_TOKEN name is not important other than that it matches the usage in the workflow:

1- name: Publish packages 2 run: npx nx release publish 3 shell: bash 4 env: 5 NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }} 6 NPM_CONFIG_PROVENANCE: true 7

NPM Provenance

To verify your packages with npm provenance, set the NPM_CONFIG_PROVENANCE environment variable to true in the step where nx release publish is performed. The workflow will also need the id-token: write permission to generate the provenance data:

1jobs: 2 test: 3 name: Publish 4 runs-on: ubuntu-latest 5 permissions: 6 contents: read 7 id-token: write # needed for provenance data generation 8
1- name: Publish packages 2 run: npx nx release publish 3 shell: bash 4 env: 5 NODE_AUTH_TOKEN: ${{ secrets.NPM_ACCESS_TOKEN }} 6 NPM_CONFIG_PROVENANCE: true 7

Publishing Docker Images (Experimental)

Experimental Feature

Docker support in Nx is currently experimental and may undergo breaking changes without following semantic versioning.

Nx Cloud Agents Compatibility

Docker operations in nx release are currently supported in standard CI/CD environments like GitHub Actions, GitLab CI, and Jenkins.

For Nx Cloud Agents compatibility, please contact Nx Enterprise support to explore available options for your team.

When using Nx Release with Docker images, the publishing process differs from npm packages.

Docker images are built with the npx nx run-many -t docker:build command, which is the default for preVersionCommand in nx.json.

You may also run the build command manually before running nx release. After the images are built, they are tagged during the versioning phase, then pushed to a registry during the publish phase.

Docker Registry Authentication

Before publishing Docker images, ensure you're authenticated with your Docker registry:

.github/workflows/publish.yml
1- name: Login to Docker Hub 2 uses: docker/login-action@v2 3 with: 4 username: ${{ secrets.DOCKER_USERNAME }} 5 password: ${{ secrets.DOCKER_TOKEN }} 6 7- name: Build and tag Docker images 8 run: npx nx release version --dockerVersionScheme=production 9 10- name: Publish Docker images 11 run: npx nx release publish 12

For changelogs, you can run npx nx release changelog <version> locally with the new version from the pipeline. For example, if the new version is 2501.01.be49ad6 you would run npx nx release changelog 2501.01.be49ad6. This will create or update the CHANGELOG.md files in your projects.

Using Different Registries

Configure alternative registries in your nx.json:

nx.json
1{ 2 "release": { 3 "docker": { 4 "registryUrl": "ghcr.io" // GitHub Container Registry 5 } 6 } 7} 8

Example GitHub Actions Workflow for Docker

.github/workflows/docker-publish.yml
1name: Docker Publish 2 3on: 4 push: 5 branches: [main] 6 7jobs: 8 publish: 9 runs-on: ubuntu-latest 10 steps: 11 - uses: actions/checkout@v3 12 13 - name: Setup Node.js 14 uses: actions/setup-node@v3 15 with: 16 node-version: 20 17 18 - name: Install dependencies 19 run: npm ci 20 21 - name: Build applications 22 run: npx nx run-many -t build 23 24 - name: Login to Docker Hub 25 uses: docker/login-action@v2 26 with: 27 username: ${{ secrets.DOCKER_USERNAME }} 28 password: ${{ secrets.DOCKER_TOKEN }} 29 30 - name: Build and tag Docker images 31 run: npx nx release version --dockerVersionScheme=production 32 33 - name: Publish Docker images 34 run: npx nx release publish 35