Workflow

Here's a typical end-to-end versioning workflow using Nyron, from checking changes to creating a release.

Complete Release Workflow

Basic Workflow (Simplest)

The simplest workflow without manual tag pushing:

# 1. Bump version and generate changelog
npx @nyron/cli bump --type minor --prefix v

# 2. Commit changes
git add .
git commit -m "chore: bump version to 1.2.0"

# 3. Create GitHub release
# Note: Requires at least one existing nyron-release tag.
# After creating the release, it will create a NEW tag for the NEXT release.
npx @nyron/cli release

# 4. Push commits and tags (including the new tag created by release)
git push --follow-tags

The release command automatically:

• Finds the latest nyron-release@* tag (requires at least one to exist)
• Fetches commits since that tag to HEAD
• Creates the GitHub release with auto-generated changelog
• Creates a new nyron-release@* tag AFTER the release (marks boundary for NEXT release)
• Updates meta.json with the new tag

Important: The tag is created AFTER the release, not before. Make sure to push tags with git push --follow-tags or git push && git push --tags.

Workflow with GPG-Signed Tags (Recommended)

If you want to GPG-sign your release tags locally before pushing:

# 1. Bump version and generate changelog
npx @nyron/cli bump --type minor --prefix v

# 2. Commit changes
git add .
git commit -m "chore: bump version to 1.2.0"

# 3. Create and push GPG-signed nyron-release tag
npx @nyron/cli push-tag

# 4. Create GitHub release (use -n since tag already exists)
npx @nyron/cli release -n

# 5. Push commits
git push

Why use this workflow?

• GPG signs the tag locally before pushing
• Provides cryptographic verification
• Shows "Verified" badge on GitHub
• Proves authenticity of the release
• Works seamlessly with CI/CD workflows

Understanding the -n flag: When you use push-tag, it creates a nyron-release@* tag. The -n flag tells release to:

• Use the existing tag you just pushed (instead of creating a duplicate)
• Fetch commits BETWEEN the previous tag and the tag you just pushed
• NOT create a new tag after the release

Without -n, release would fetch commits FROM the latest tag to HEAD and create a new tag AFTER the release (for the next release), which isn't what you want when you've already pushed a tag.

Monorepo Workflow

For monorepos with multiple packages, the workflow is the same but you specify which package to release:

Basic Monorepo Workflow

# Bump specific package
npx @nyron/cli bump --type patch --prefix @myapp/api@

# Commit changes
git add .
git commit -m "chore(api): bump version to 1.0.1"

# Create release
# Note: After creating the release, it will create a NEW tag for the NEXT release.
npx @nyron/cli release

# Push commits and tags (including the new tag created by release)
git push --follow-tags

With GPG-Signed Tags

# Bump specific package
npx @nyron/cli bump --type patch --prefix @myapp/api@

# Commit changes
git add .
git commit -m "chore(api): bump version to 1.0.1"

# Create GPG-signed tag
npx @nyron/cli push-tag

# Create release (skip tag creation)
npx @nyron/cli release -n

# Push commits
git push

Version Bump Decision Guide

Choose the appropriate bump type based on your changes:

Major (--type major)

Use for breaking changes that require users to update their code:

• API changes that break compatibility
• Removal of deprecated features
• Major architectural changes

Example: 1.5.2 → 2.0.0

Minor (--type minor)

Use for new features that are backward compatible:

• New functionality
• New API endpoints
• Feature enhancements

Example: 1.5.2 → 1.6.0

Patch (--type patch)

Use for bug fixes and minor updates:

• Bug fixes
• Documentation updates
• Performance improvements (non-breaking)

Example: 1.5.2 → 1.5.3

Automated Release Workflow

You can set up a GitHub Actions workflow that automatically creates releases when you push nyron-release tags locally. This is useful for:

• GPG-signing tags locally before pushing
• Triggering automated release creation
• Separating local development from release publishing

Setup CI/CD Workflow

Create .github/workflows/release.yml in your repository:

name: Publish Github Release Using Nyron

on:
  push:
    tags:
      - 'nyron-release@*'

permissions:
  contents: write

jobs:
  publish-release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history to ensure latest tag is available
      
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install
      - run: bun x @nyron/cli release -n
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Note: The -n flag tells the release command to use the existing nyron-release@* tag you pushed with push-tag, rather than creating a duplicate tag. This is essential when using CI/CD workflows.

Usage

When ready to release:

# 1. Bump and commit
npx @nyron/cli bump --type minor --prefix v
git add . && git commit -m "chore: bump version to 1.2.0"

# 2. Push tag (creates GPG-signed tag and triggers the workflow)
npx @nyron/cli push-tag

# 3. Push your commits
git push

# The GitHub Actions workflow automatically creates the release! 🎉

Comparison: Local vs Automated

Local Release (No CI/CD):

npx @nyron/cli bump --type minor --prefix v
git add . && git commit -m "chore: bump version to 1.2.0"
npx @nyron/cli release  # Creates release, then creates tag for NEXT release
git push --follow-tags  # Push commits and the new tag

Automated Release (With CI/CD):

npx @nyron/cli bump --type minor --prefix v
git add . && git commit -m "chore: bump version to 1.2.0"
npx @nyron/cli push-tag  # Creates GPG-signed tag, triggers CI/CD
git push  # CI/CD creates the release for you (using -n flag)

Benefits of Automated Workflow:

• ✅ GPG-sign tags locally for verified releases
• ✅ Separate concerns (local dev vs release publishing)
• ✅ Consistent release environment
• ✅ No need to have GITHUB_TOKEN locally

Customizing the Workflow

You can modify the workflow to use npm, pnpm, or Node.js instead of Bun:

# For npm
- uses: actions/setup-node@v4
  with:
    node-version: '20'
- run: npm install
- run: npx @nyron/cli release

# For pnpm
- uses: pnpm/action-setup@v2
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm exec @nyron/cli release

Pro Tips

Use the reminder feature

If you have onPushReminder: true in your config, Nyron will remind you to push your tags after creating them.

Preview releases

You can preview what will be included in a release using the dry-run flag:

npx @nyron/cli release --dry-run

Consistent commit messages

The better your commit messages follow conventional commits, the better your changelog will look.

Configure GitHub repository settings

For the best experience with Nyron, configure your GitHub repository to enforce clean commit history and conventional commit format. See the GitHub repository setup guide for detailed instructions.

Next Steps

• Learn about all available commands
• Understand how Nyron works under the hood
• Review configuration options
• Set up GitHub repository settings