Automate versioning and publishing with Nx

A reusable GitHub workflow that automates package versioning and publishing for Nx monorepos using Nx Release with version plans.

Features

🔄 Automatically creates or updates a Version Packages pull request when new version plans are added
📦 Publishes packages to npm when the Version Packages PR is merged
🎯 Agnostic: Works with pnpm, yarn, and npm
♻️ Idempotent: workflow_dispatch can recover missed tags or releases

How It Works

The workflow automates the full release lifecycle in two steps:

When you push a version plan to main — the workflow opens (or updates) a Version Packages pull request that bumps versions and updates changelogs automatically.
When the Version Packages PR is merged — the workflow publishes the packages to npm with provenance, creates git tags, and creates the corresponding GitHub Releases.

Recovery

If something goes wrong mid-publish, re-run the action or trigger workflow_dispatch manually. The workflow will pick up from where it left off, creating only the missing tags and releases.

Prerequisites

Repository configured with nx.json (see nx.json configuration below)
npm packages require OIDC Trusted Publishing configured (id-token: write permission must be granted)
Public packages must be tagged as public in their Nx project configuration. The nx-release workflow treats any tag equal to public or ending with :public (for example, npm:public) as publishable.

Marking a package as public

To mark a package as public, set "private": false in the package's package.json file. This is necessary for the publish workflow to process the package:

{
  "name": "@pagopa/my-package",
  "version": "1.0.0",
  "private": false,
  ... other package.json fields
}

nx.json configuration

Add the following release block to your nx.json:

{
  "release": {
    "versionPlans": true,
    "projects": [
      "apps/*",
      "packages/*",
      ... other project globs
    ],
    "projectsRelationship": "independent",
    "version": {},
    "changelog": {
      "projectChangelogs": {
        "createRelease": false,
        "file": "{projectRoot}/CHANGELOG.md",
        "renderOptions": {
          "authors": true,
          "applyUsernameToAuthors": true,
          "commitReferences": true,
          "versionTitleDate": true
        }
      }
    },
    "git": {
      "commit": false,
      "tag": true,
      "stageChanges": false
    },
    "releaseTag": {
      "pattern": "{projectName}@{version}"
    }
  }
}

Option	Value	Why
`versionPlans`	`true`	Enables file-based versioning via version plans: version increments are described in dedicated files committed to the repo
`projects`	`["projects_path_1/*", ...]`	Glob patterns matching all projects to include in the release process; required for Nx to discover and release all packages
`projectsRelationship`	`"independent"`	Each package has its own version; there is no single workspace-wide version
`createRelease`	`false`	GitHub Releases are created automatically by the workflow after the PR is merged, not at changelog generation time
`git.commit`	`false`	The workflow handles commits itself; letting Nx commit would interfere with the PR creation logic
`git.tag`	`true`	Nx creates tags locally so the workflow can reference them; they are pushed only after the PR is merged
`releaseTag.pattern`	`{projectName}@{version}`	Follows the default Nx independent release convention; defining it explicitly improves clarity

note

The key renderOptions just adds some extra details to the changelog, but it doesn't affect the release process. You can omit it if you don't need those details (refer to the Nx documentation).

Usage

Use the release-v2.yaml reusable workflow. Create a .github/workflows/release.yaml file:

name: Release

on:
  push:
    branches:
      - main
    paths:
      - ".nx/version-plans/**" # Optional, but recommended to avoid unnecessary workflow runs on unrelated changes
  workflow_dispatch:

concurrency: ${{ github.workflow }}-${{ github.ref }}

jobs:
  release:
    name: Nx Release
    permissions:
      contents: write
      id-token: write
      pull-requests: write
    uses: pagopa/dx/.github/workflows/release-v2.yaml@main
    with:
      environment: npm-prod-cd
    secrets:
      github-token: ${{ secrets.GITHUB_TOKEN }}

Inputs

Input	Description	Required	Default
`environment`	Repository Environment to associate with the release job	Yes	`app-prod-cd`

Secrets

Secret	Description	Required
`github-token`	GitHub token with `contents:write` and `pull-requests:write` permissions	Yes

Required Permissions

permissions:
  contents: write # To push version bumps, tags, and commits
  id-token: write # For npm provenance (trusted publishing)
  pull-requests: write # To create/update the Version Packages PR

Starting a Release

A release starts by committing a version plan to main. A version plan is a small file that records which packages changed and how their version should be bumped.

1. Generate the version plan

From the root of the repository, run:

npx nx release plan

The command is interactive: it will ask which packages to include and what bump type to apply (patch / minor / major / prerelease / prepatch / preminor / premajor). At the end it writes a file under .nx/version-plans/.

For more details see the Nx version plans documentation.

2. Commit and push

git add .nx/version-plans/
git commit -m "feat: update @pagopa/my-package"
git push origin main

Pushing to main triggers the workflow, which opens (or updates) the Version Packages PR automatically. Merging that PR publishes the packages.

info

The direct push to main is a simplified flow for demonstration purposes. In a real-world scenario, you might want to create a PR for the version plan changes as well.

Troubleshooting

Version Packages PR is not created

Ensure .nx/version-plans/ contains version plan files on main
Verify the GitHub token has pull-requests: write permission
Run nx release --dry-run locally to check for errors

Publish fails

Verify that packages have the npm:public tag in their Nx configuration
Check that OIDC trusted publishing is configured on npm
Ensure id-token: write permission is granted to the workflow

Git tags or GitHub Releases are missing

Trigger workflow_dispatch manually. The action scans all past merged Version Packages PRs and creates any tags and releases still missing.

Features​

How It Works​

Prerequisites​

Marking a package as public​

nx.json configuration​

Usage​

Inputs​

Secrets​

Required Permissions​

Starting a Release​

1. Generate the version plan​

2. Commit and push​

Troubleshooting​

Version Packages PR is not created​

Publish fails​

Git tags or GitHub Releases are missing​

Related Documentation​