Skip to content

RELEASE.md

Latest commit

 

History

History
173 lines (119 loc) · 4.07 KB

RELEASE.md

File metadata and controls

173 lines (119 loc) · 4.07 KB

Release Process

This document explains how to release a new version of @permify/permify-node to NPM.

Overview

The release process is fully automated using GitHub Actions. When you create a GitHub release, the package is automatically published to NPM.

How to Release

1. Prepare

Make sure everything is ready:

# Pull latest changes
git checkout main
git pull origin main

# Run tests
yarn run-test

# Build the project
yarn build

2. Choose Version Number

Follow Semantic Versioning:

  • MAJOR (x.0.0) - Breaking changes
  • MINOR (0.x.0) - New features (backward compatible)
  • PATCH (0.0.x) - Bug fixes

Examples:

  • 1.1.1 → 1.1.2 (bug fix)
  • 1.1.2 → 1.2.0 (new feature)
  • 1.2.0 → 2.0.0 (breaking change)

3. Create GitHub Release

  1. Go to Releases
  2. Click "Draft a new release"
  3. Fill in the details:
    • Tag version: v1.2.0 (must start with v)
    • Release title: v1.2.0
    • Description: List changes, new features, and bug fixes
  4. Click "Publish release"

4. Automatic Publishing

Once published, GitHub Actions will:

  • Build the package
  • Extract version from tag (e.g., v1.2.0 → 1.2.0)
  • Update package.json version
  • Publish to NPM

Track progress at: https://github.com/Permify/permify-node/actions

5. Verify

Check that the new version is live:

npm view @permify/permify-node version

Proto Updates

Proto definitions are automatically synced from Buf Schema Registry.

Automatic Updates

The proto workflow runs on every push to main:

  • Generates TypeScript code from latest proto definitions
  • Creates a pull request if changes are detected
  • PR branch: proto-update/permify-latest

Manual Update

To manually update protos:

yarn buf:generate

Configuration

Trusted Publisher

Publishing uses npm trusted publishing, so no long-lived npm publish token is required.

Configure the trusted publisher in the npm package settings:

  • Publisher: GitHub Actions
  • Organization or user: Permify
  • Repository: permify-node
  • Workflow filename: publish.yml
  • Allowed actions: npm publish
  • Environment name: leave empty unless .github/workflows/publish.yml is updated to use a matching GitHub environment

Workflows

1. Publish Workflow (.github/workflows/publish.yml)

Trigger: GitHub release published

Steps:

  1. Checkout code
  2. Setup Node.js with npm trusted publishing support
  3. Install dependencies
  4. Build (yarn build)
  5. Update version
  6. Publish to NPM using GitHub OIDC

2. Proto Update Workflow (.github/workflows/protos.yml)

Trigger: Push to main or manual dispatch

Steps:

  1. Setup Buf CLI
  2. Generate TypeScript code
  3. Create PR if changes detected

Troubleshooting

Build Failed

# Test locally
yarn build

Publish Failed

  • Verify the npm trusted publisher settings match Permify/permify-node and publish.yml
  • Check that the workflow has id-token: write permission
  • Verify version doesn't already exist on NPM
  • Check Actions logs

Wrong Version Published

If you published the wrong version:

  1. Delete the GitHub release
  2. Delete the Git tag: 
    git tag -d v1.2.0
git push origin :refs/tags/v1.2.0
  3. Unpublish from NPM (within 24 hours): 
    npm unpublish @permify/permify-node@1.2.0

Note: After 24 hours, you cannot unpublish. Release a new patch version instead.

Release Checklist

Before releasing:

  • All tests pass
  • Code reviewed and merged
  • Version number follows semantic versioning
  • Release notes prepared
  • Breaking changes documented (if any)
  • npm trusted publisher is configured for .github/workflows/publish.yml

Links