@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 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)

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

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

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