@tantawowa/hosanna-release-tool

A transactional release management tool for GitHub Actions workflows. Reduces duplication across repos with a two-phase pattern: validate/prepare then commit.

Features

• 🎯 Transactional Pattern - Two-phase operations: validate/prepare, then commit
• 🔄 Release Management - Start, bump, finish, abort, and delete releases
• 📦 Multi-Project Support - Works with Roku apps, npm packages, and browser extensions
• ✅ Fail Fast - Validation happens before any commits
• 🧪 Testable - Run lint/test between prepare and commit phases
• 📤 CI-Friendly - Uses existing git/auth context from GitHub Actions
• 🚫 Non-Destructive - Prepare phase updates files but doesn't commit

Installation

npm install -g @tantawowa/hosanna-release-tool

Or use with npx:

npx @tantawowa/hosanna-release-tool start minor

Transactional Pattern

Commands work in two phases:

1. Validate & Prepare (default): Run command without --commit

   • Validates inputs and git state
   • Updates files (package.json, manifest)
   • Stores state in .hrt-state.json
   • Does NOT commit or push

2. Commit: Run command with --commit flag

   • Reads state from .hrt-state.json
   • Commits and pushes changes
   • Clears state after success

Commands

hrt start <version>

Start a new release. Creates release branch and bumps to rc.0.

# Validate & prepare
hrt start minor
hrt start 1.2.3
hrt start patch --source-branch=main

# Commit (after validation steps)
hrt start --commit

Options:

• --source-branch <branch> - Source branch to create release from (default: main)
• --commit - Commit and push changes

hrt bump

Bump RC version on existing release branch.

# Validate & prepare
hrt bump --release-branch=release/1.2.3
hrt bump  # Auto-detects from current branch

# Commit (after validation steps)
hrt bump --commit

Options:

• --release-branch <branch> - Release branch to bump (auto-detected if on release branch)
• --commit - Commit and push changes

hrt finish

Finish release. Strips RC suffix and creates final tag.

# Validate & prepare
hrt finish --release-branch=release/1.2.3
hrt finish  # Auto-detects from current branch

# Commit (after validation steps)
hrt finish --commit

Options:

• --release-branch <branch> - Release branch to finish (auto-detected if on release branch)
• --commit - Commit and push changes

hrt release <version>

Create a quick release without RC versions. Creates release branch with final version, tags it, and optionally creates GitHub release.

# Validate & prepare (creates release branch by default)
hrt release minor
hrt release 1.2.3
hrt release patch --source-branch=main

# Quick release directly to source branch (no release branch)
hrt release minor --no-branch
hrt release 1.2.3 --no-branch --source-branch=main

# Commit (after validation steps)
hrt release --commit

Options:

• --source-branch <branch> - Source branch to create release from (default: main)
• --commit - Commit and push changes
• --no-branch - Release directly to source branch without creating a release branch (useful for CI/CD quick releases)

When to use --no-branch:

• CI/CD workflows: When you want a simple, fire-and-forget release workflow
• Automated releases: When you don't need a separate release branch for review
• Quick releases: When you want to release directly to main/master without intermediate branches

When NOT to use --no-branch (default behavior):

• Manual releases: When you want to review changes before merging
• Release branches: When you need to keep release history separate from main
• Multiple releases: When you might need to create multiple releases from the same base

Note: This command creates a release branch with the final version (no RC suffix) by default. Use hrt start if you need RC versions for testing. Use --no-branch for quick CI/CD releases.

hrt update-main <version>

Create a pull request to bump the main branch version. Useful for updating main after a release.

hrt update-main 1.4.0
hrt update-main 1.4.0 --source-branch=main --target-branch=main

Options:

• --source-branch <branch> - Source branch to create PR from (default: main)
• --target-branch <branch> - Target branch for PR (default: same as source-branch)

Note: This command creates a new branch, updates version files, commits, pushes, and creates a PR automatically.

hrt abort <version>

Abort in-progress release. Deletes branch, RC tags, and draft releases (not final tags).

hrt abort 1.2.3

hrt delete <version>

Delete release. Full deletion: branch, all tags (including final), draft releases.

hrt delete 1.2.3

hrt getVersion

Get current version in various formats.

hrt getVersion                    # Full: 1.2.3-rc.1
hrt getVersion --format=condensed  # Condensed: 1.2.3.1
hrt getVersion --format=base       # Base: 1.2.3
hrt getVersion --format=tag         # Tag: v1.2.3

hrt validate-env

Validate required environment variables. Checks for all required environment variables and provides clear feedback.

hrt validate-env
# Checks:
#   - GITHUB_TOKEN (required)
#   - Repository detection (GITHUB_REPOSITORY or git remote)
#   - XAI_API_KEY (optional, for changelog generation)

# Validate update-main requirements
hrt validate-env --check-update-main --next-main-version=1.4.0
# Also validates:
#   - Next main version is provided
#   - Next main version is valid semver format

Options:

• --check-update-main - Check if update-main is requested
• --next-main-version <version> - Validate next main version (required if --check-update-main is set)

Output:

• ✓ All required environment variables are present. (exit code 0)
• ✗ Some required environment variables are missing. (exit code 1)

hrt release-set-env-variables

Output environment variables for build scripts.

eval $(hrt release-set-env-variables)
# Sets: HRT_BUILD_VERSION, HRT_BUILD_VERSION_CONDENSED, HRT_BUILD_VERSION_BASE, HRT_BUILD_TAG

GitHub Actions Integration

Example: release-start.yml

- name: Start release (validate & prepare)
  run: |
    npx @tantawowa/hosanna-release-tool start \
      "${{ github.event.inputs.version }}" \
      --source-branch="${{ github.event.inputs.source-branch || 'main' }}"
  # hrt validates, creates branch, updates files, stores state
  # Exits with error if validation fails

- name: Lint
  run: npm run lint

- name: Test
  run: npm run test

- name: Commit release start
  run: npx @tantawowa/hosanna-release-tool start --commit
  # Commits package.json, manifest, and changelog changes
  # Pushes release branch

Example: release-bump.yml

- name: Bump RC version (validate & prepare)
  run: |
    npx @tantawowa/hosanna-release-tool bump \
      --release-branch="${{ github.event.inputs.release-branch }}"
  # Updates version files, doesn't commit

- name: Lint
  run: npm run lint

- name: Test
  run: npm run test

- name: Commit bump
  run: npx @tantawowa/hosanna-release-tool bump --commit
  # Commits version bump and changelog changes

Example: release-finish.yml

- name: Finish release (validate & prepare)
  run: |
    npx @tantawowa/hosanna-release-tool finish \
      --release-branch="${{ github.event.inputs.release-branch }}"
  # Validates branch, creates final tag if needed, updates to final version

- name: Lint
  run: npm run lint

- name: Test
  run: npm run test

- name: Commit finish
  run: npx @tantawowa/hosanna-release-tool finish --commit
  # Commits final version changes, pushes branch with final tag

Example: release.yml (Quick Release)

Option 1: With release branch (default, recommended for manual releases)

- name: Release (validate & prepare)
  run: |
    npx @tantawowa/hosanna-release-tool release \
      "${{ github.event.inputs.version }}" \
      --source-branch="${{ github.event.inputs.source-branch || 'main' }}"
  # Validates, creates release branch, updates files, creates tag, stores state

- name: Lint
  run: npm run lint

- name: Test
  run: npm run test

- name: Commit release
  run: npx @tantawowa/hosanna-release-tool release --commit
  # Commits and pushes release branch with final tag
  # Creates GitHub release if configured

Option 2: Direct release (use --no-branch for CI/CD quick releases)

inputs:
  version:
    description: 'Version bump type: major, minor, patch, or specific version (e.g., 1.2.1)'
    required: true
    type: string
  source-branch:
    description: 'Source branch to release from (e.g., main)'
    required: false
    default: main
    type: string
  no-branch:
    description: 'Release directly to source branch without creating release branch'
    required: false
    default: false
    type: boolean

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Release (validate & prepare)
        run: |
          npx @tantawowa/hosanna-release-tool release \
            "${{ github.event.inputs.version }}" \
            --source-branch="${{ github.event.inputs.source-branch || 'main' }}" \
            ${{ github.event.inputs.no-branch == 'true' && '--no-branch' || '' }}
        # If --no-branch: releases directly to source branch (no release branch created)
        # Otherwise: creates release branch (default behavior)

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm run test

      - name: Commit release
        run: npx @tantawowa/hosanna-release-tool release --commit
        # Commits and pushes to release branch (or source branch if --no-branch was used)
        # Creates GitHub release if configured

When to use --no-branch in CI/CD:

• Set no-branch: true in workflow inputs for automated, quick releases
• Use default (no-branch: false) when you want to review the release branch before merging

Example: update-main-version.yml

- name: Validate update-main requirements
  run: |
    npx @tantawowa/hosanna-release-tool validate-env \
      --check-update-main \
      --next-main-version="${{ github.event.inputs.next-main-version }}"
  # Validates that next-main-version is provided and valid
  # Fails early if validation fails

- name: Create PR to update main version
  run: |
    npx @tantawowa/hosanna-release-tool update-main \
      "${{ github.event.inputs.next-main-version }}" \
      --source-branch="${{ github.event.inputs.source-branch || 'main' }}"
  # Creates branch, updates version files, commits, pushes, and creates PR

Project Types

The tool auto-detects project type:

• Roku: Detects platforms/roku/src/manifest and syncs version
• npm Package: Updates package.json version
• Browser Extension: Updates manifest.json if present

Configuration

Create a .hrt-config.json file in your project root to customize release behavior:

{
  "releases": {
    "create": true,
    "when": "finish",
    "body": "auto",
    "name": "Release {version}"
  },
  "assets": {
    "patterns": ["dist/**/*.zip", "build/*.tgz"],
    "files": ["CHANGELOG.md"],
    "exclude": ["**/*.map"],
    "maxSize": 100
  }
}

Release Options

• releases.create (boolean, default: true): Whether to create GitHub releases
• releases.when ("finish" | "bump" | "never", default: "finish"):
  • "finish": Only create final releases when finishing
  • "bump": Create draft releases on bump, final on finish
  • "never": Never create releases (useful for npm packages)
• releases.body ("auto" | string, default: "auto"): Release body content
  • "auto": Use changelog entry
  • Custom string: Supports {version}, {tag}, {changelog} placeholders
• releases.name (string, default: "{tag}"): Release name template
  • Supports {version}, {tag} placeholders

Asset Options

• assets.patterns (string[], default: []): Glob patterns to match files
• assets.files (string[], default: []): Specific file paths to include
• assets.exclude (string[], default: []): Glob patterns to exclude
• assets.maxSize (number, default: 100): Maximum file size per asset in MB

Examples

Disable GitHub releases (for npm packages):

{
  "releases": {
    "create": false
  }
}

Upload build artifacts:

{
  "assets": {
    "patterns": ["dist/**/*.{zip,tgz,tar.gz}"],
    "exclude": ["**/*.map", "**/*.test.*"]
  }
}

Create draft releases on bump:

{
  "releases": {
    "when": "bump"
  }
}

State Management

State is stored in .hrt-state.json (should be gitignored):

{
  "operation": "start",
  "version": "1.2.3-rc.0",
  "baseVersion": "1.2.3",
  "branch": "release/1.2.3",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Requirements

• Node.js 16+
• Git (for version control operations)
• GITHUB_TOKEN environment variable (for GitHub API operations)

Use hrt validate-env to check that all required environment variables are set.

Error Handling

Commands fail fast with clear error messages:

• Validation errors exit before any commits
• Git errors preserve git state
• State validation ensures operations match

Examples

Complete Release Workflow

# 1. Start release
hrt start minor
npm run lint && npm run test
hrt start --commit

# 2. Bump RC
hrt bump
npm run lint && npm run test
hrt bump --commit

# 3. Finish release
hrt finish
npm run lint && npm run test
hrt finish --commit

Using in CI/CD

- name: Set version env vars
  run: |
    eval $(npx @tantawowa/hosanna-release-tool release-set-env-variables)
    echo "HRT_BUILD_VERSION=$HRT_BUILD_VERSION" >> $GITHUB_ENV
    echo "HRT_BUILD_VERSION_CONDENSED=$HRT_BUILD_VERSION_CONDENSED" >> $GITHUB_ENV

Contributing

See migration-guide.md for details on migrating existing workflows.

License

ISC