@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 [vars...]

Validate required environment variables. Can validate specific variables or use default set.

# Validate default set of environment variables
hrt validate-env

# Validate specific environment variables
hrt validate-env GITHUB_TOKEN GITHUB_REPOSITORY
hrt validate-env GITHUB_TOKEN GITHUB_REPOSITORY XAI_API_KEY

# Perfect for CI/CD one-liners
hrt validate-env GITHUB_TOKEN GITHUB_REPOSITORY || exit 1

Options:

• [vars...] - Environment variable names to validate (if not provided, validates default set)
• --check-update-main - Check if update-main is requested
• --next-main-version <version> - Next main version to validate (required if --check-update-main is set)

Exit codes:

• 0 - All required variables are present
• 1 - One or more required variables are missing

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)

Environment Variables

Required:

• GITHUB_TOKEN - Required for GitHub API operations (creating/updating/deleting releases)

Optional:

• GITHUB_REPOSITORY - Repository owner/name (auto-detected from git remote if not set)
• XAI_API_KEY - Required for changelog generation scripts (not used by release tool)

Validation: Use hrt validate-env to check environment variables before running release commands:

# Validate specific variables
hrt validate-env GITHUB_TOKEN GITHUB_REPOSITORY

# Or validate default set
hrt validate-env

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

# Validate environment variables before running release commands
- name: Validate environment
  run: |
    npx @tantawowa/hosanna-release-tool validate-env \
      GITHUB_TOKEN GITHUB_REPOSITORY || exit 1

# Set version env vars
- 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

Integration Tests

The project includes comprehensive integration tests that verify the complete release workflow end-to-end. These tests perform real git operations and GitHub API calls, so they require proper setup.

Prerequisites

1. Create a .secrets file in the project root with your GitHub token:

   GITHUB_TOKEN=your_github_token_here

   Or for Bitbucket:

   BITBUCKET_TOKEN=your_bitbucket_token_here

   Or use a generic token:

   GIT_TOKEN=your_token_here

2. Ensure you have a clean git state - the tests will create and delete branches/tags

Running Integration Tests

Run all integration tests in sequence:

npm run test:integration

This will run the complete test suite:

• start - Tests creating a new release branch
• bump - Tests bumping RC versions
• finish - Tests finishing a release
• config - Tests configuration file behavior
• delete - Tests deleting releases
• verify - Verifies cleanup was successful

Run individual integration tests:

npm run test:start    # Test start release workflow
npm run test:bump     # Test bump release workflow
npm run test:finish   # Test finish release workflow
npm run test:delete   # Test delete release workflow
npm run test:verify   # Verify cleanup

Note: All integration test scripts automatically build the project before running tests.

What the Tests Do

The integration tests:

• Create real release branches and tags
• Make actual GitHub API calls to create/update/delete releases
• Verify git state, branches, tags, and releases
• Clean up test artifacts after completion

The tests use version 99.99.99 for the main test release, and versions 99.99.97, 99.99.96, 99.99.95 for config tests.

Contributing

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

License

ISC