Node GitHub Local Release

This sample releases a Node.js package from local npm scripts:

• npm run release:major creates a major version bump.
• npm run release:minor creates a minor version bump.
• npm run release:patch creates a patch version bump.

The helper uses npm version, which updates package.json, creates the release commit, and creates the matching Git tag automatically. It then pushes the commit and tag, and creates a GitHub Release with the GitHub CLI.

Files

• scripts/release-helper.js validates the release type, checks out the target branch, runs npm version, pushes the release commit and tag, and creates the GitHub Release.
• package.json exposes local release scripts.

Requirements

• Node.js and npm.
• GitHub CLI installed as gh.
• GitHub CLI authenticated with gh auth login.
• A Git remote named origin.
• A clean working tree before running a release.

GitHub Auth

Authenticate the GitHub CLI:

gh auth login

If you use multiple GitHub accounts, switch to the account for this repository before releasing:

gh auth switch
gh auth setup-git

gh auth setup-git configures Git HTTPS operations so git fetch, git pull, and git push can use your selected GitHub CLI account.

Release Commands

Patch release:

npm run release:patch

Minor release:

npm run release:minor

Major release:

npm run release:major

You can also pass the type directly:

npm run release -- patch

The release target branch defaults to main. To release from another branch:

TARGET_BRANCH=develop npm run release:patch

To push the release commit and tag without creating a GitHub Release:

SKIP_GITHUB_RELEASE=1 npm run release:patch

What The Helper Does

1. Reads the release type from the npm script: major, minor, or patch.
2. Verifies the working tree is clean before changing any files.
3. Fetches the target branch and tags from origin.
4. Checks out the target branch and pulls the latest changes.
5. Calculates the next version and checks that the tag does not already exist locally or on origin.
6. Runs npm version major, npm version minor, or npm version patch.
7. Pushes the release commit to the target branch.
8. Pushes the new version tag.
9. Runs gh release create for the new tag unless SKIP_GITHUB_RELEASE=1 is set.

How It Works

flowchart LR
  A[npm run release:*] --> B[Check repo]
  B --> C[npm version]
  C --> D[Push commit and tag]
  D --> E[Create GitHub Release]

Loading

Why This Pattern

Using npm version keeps the package version, release commit, and Git tag consistent. The helper keeps the release flow local, so you can choose the correct GitHub CLI account with gh auth switch before running the release.

The script checks for a clean working tree and existing tags before creating the release. That prevents accidental releases from uncommitted changes and avoids overwriting an existing version tag.