Quickstart

This guide will help you set up Nyron in your project and create your first automated release.

Initialize Nyron

Run the initialization command to create a configuration file:

npx @nyron/cli init

This creates a nyron.config.ts file plus .nyron/meta.json and .nyron/versions.json.

For a single-package repository, the generated config looks like this:

import { defineConfig } from "@nyron/cli/config"

export default defineConfig({
  repo: "owner/repo", // Your GitHub repo
  projects: {
    main: {
      tagPrefix: "v",
      path: ".",
    },
  },
})

For monorepos, Nyron detects workspace packages and creates one project entry per package.

Review this file and adjust it if needed.

Single-Package Repository

For a single-package repo, use this simpler configuration:

import { defineConfig } from "@nyron/cli/config"

export default defineConfig({
  repo: "your-org/your-repo",
  projects: {
    main: {
      tagPrefix: "v",
      path: ".",
    },
  },
})

Setup GitHub Token (Required for Publishing)

You only need a GitHub token when you want to publish a GitHub release:

# Create .env in your project root
echo "GITHUB_TOKEN=your_github_token_here" > .env

Generate a token at GitHub Settings → Developer settings → Personal access tokens and ensure you check all of the following permissions:

• repo (Full control of private repositories)
• repo:status (Access commit status)
• repo_deployment (Access deployment status)
• public_repo (Access public repositories)
• repo:invite (Access repository invitations)
• security_events (Read and write security events)

Understanding Nyron Tags

Nyron uses a dual-tag system that separates version tracking from release boundaries:

Project Tags (Version Tracking)

• Format: v1.2.0, @pkg/name@1.2.0 (based on your tagPrefix config)
• Created by: nyron bump command
• Purpose: Track package versions in your repository
• Used for: Version metadata, changelog file generation

Nyron-Release Tags (Release Boundaries)

• Format: nyron-release@2024-01-15@14-30-25.123
• Created by: nyron push-tag or nyron release command
• Purpose: Mark release boundaries for GitHub releases
• Used for: Determining which commits to include in releases

Starting with an Existing Repository

If your repository already has many commits and tags (e.g., 500+ commits with various version tags), here's how to get started:

Step 1: Initialize Nyron

npx @nyron/cli init

Edit nyron.config.ts to match your project structure. Your existing tags won't interfere with Nyron.

Step 2: Create Your First Nyron-Release Tag

For existing repositories, you need to establish a baseline nyron-release tag. This marks where Nyron will start tracking releases from:

# First, bump your version (if needed)
npx @nyron/cli bump --type minor

# Commit the changes
git add .
git commit -m "chore: initialize nyron"

# Create and push the first nyron-release tag
npx @nyron/cli push-tag

This creates your first nyron-release@* tag at the current HEAD. Future releases will include commits since this tag.

Step 3: Create Your First Release

After pushing your first nyron-release tag, create a release:

# Use --use-existing-tag since you already pushed the tag
npx @nyron/cli release --use-existing-tag

The --use-existing-tag flag tells Nyron to use the existing nyron-release tag you just pushed, rather than creating a new one.

Start Using Nyron

Now you're ready to use Nyron! Here's the typical workflow:

Standard Workflow (Recommended)

This workflow uses GPG-signed tags and separates tag creation from release creation:

# 1. Bump version
npx @nyron/cli bump --type minor

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

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

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

Why use --use-existing-tag? This flag tells Nyron to use the nyron-release@* tag you just pushed with push-tag, rather than creating another boundary tag. When using it, Nyron fetches commits between the previous boundary tag and the one you just pushed. This is especially useful when:

• You want GPG-signed tags (created locally with push-tag)
• You're using CI/CD workflows that trigger on tag pushes
• You've already created a nyron-release tag manually
• You want to control exactly when tags are created

Simplified Workflow (Alternative)

If you don't need GPG-signed tags, you can let release create the tag automatically:

# 1. Bump version
npx @nyron/cli bump --type minor

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

# 3. Create GitHub release
# Note: This 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

Important: When using release without --use-existing-tag, it creates a new nyron-release@* tag after publishing. This tag marks the boundary for the next release. Make sure to push tags with git push --follow-tags or git push && git push --tags.

Next Steps

• Learn about configuration options
• Explore all available commands
• Understand how Nyron works
• Read about conventional commits