Skip to main content

Automate versioning and publishing

A reusable GitHub workflow that automates package versioning and publishing. This workflow is package-manager agnostic and works with pnpm, yarn, and npm.

Features​

  • 🔄 Automatically creates or updates release pull requests
  • 📦 Publishes packages to npm when PRs are merged
  • 🔒 Mandatory npm provenance for enhanced security
  • 🎯 Package manager agnostic (pnpm, yarn, npm)

Prerequisites​

  • Your repository must use Changesets for version management
  • A .changeset/config.json file configured in your repository
  • Changesets CLI added as a dev dependency
  • Scripts defined in package.json for versioning and publishing ( version, release)

Required Permissions​

The workflow runs with the following permissions:

permissions:
  contents: write # To push version bumps and tags
  id-token: write # For npm provenance (trusted publishing)
  pull-requests: write # To create/update release PRs
info

This workflow uses npm's trusted publishing with provenance, which eliminates the need for npm tokens.

Package.json Scripts​

Your top level package.json must include scripts for versioning and publishing:

Example with NX and pnpm​

{
  "scripts": {
    "version": "changeset version && pnpm i --lockfile-only && nx run-many --target=version",
    "release": "nx run-many --target=build --projects=tag:npm:public && changeset publish"
  }
}

Example with Turborepo and Yarn​

{
  "scripts": {
    "version": "changeset version && yarn --mode update-lockfile && turbo run version",
    "release": "turbo run build && changeset publish"
  }
}

Usage​

To use this workflow in your repository, create a new workflow file (e.g., .github/workflows/release.yaml) with the following content:

name: Release

on:
  push:
    branches:
      - main

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

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

Inputs​

InputDescriptionRequiredDefault
environmentRepository Environment that holds the github-token valueYes-

Secrets​

SecretDescriptionRequired
github-tokenGitHub token with contents:write and pull-requests:write permissionsYes

How It Works​

  1. Setup: Detects your package manager (pnpm, yarn, or npm) and sets up Node.js
  2. Install: Installs dependencies using the detected package manager
  3. Npm Update: Updates npm to version 11.8.0 to support provenance
  4. Version or Publish:
    • If there are changesets on the default branch, creates/updates a release PR
    • If the release PR is merged, publishes the new versions to npm with provenance

Environment Variables​

The workflow automatically sets:

  • GITHUB_TOKEN: For creating PRs and pushing commits (passed as secret)
  • NPM_CONFIG_PROVENANCE: Always set to true to enable npm provenance
info

No npm token is required. The workflow uses npm's trusted publishing feature with OpenID Connect (OIDC) tokens for authentication.

Troubleshooting​

Release PR is not created​

Check that:

  1. You have changeset files in the .changeset directory
  2. The GitHub token has pull-requests: write permission
  3. You're on the default branch (usually main)

Provenance error​

If you see provenance-related errors:

  • Ensure you're using an npm version that supports provenance. Minimum version is 11.5.1.
  • Verify the id-token: write permission is granted
  • Check that your npm registry supports provenance