Hotfix Post-Merge Library

A reusable TypeScript/JavaScript library for handling post-merge operations including automatic version bumping, git tagging, and repository updates.

Features

• 🚀 Automatic version detection and bumping (patch or prerelease)
• 🏷️ Git tag creation and pushing
• 🔧 Configurable via code, CLI arguments, or environment variables
• 📋 Built-in GitLab CI condition checking
• 🛡️ Error handling and rollback safety
• 📦 Works with any Node.js project using semantic versioning

Installation

As a local dependency

npm install postofmr

As a development dependency

npm install --save-dev @hose/hotfix-post-merge-lib

From a local path (for development)

npm install file:./path/to/hotfix-post-merge-lib

Quick Start

CLI Usage

The simplest way to use the library is through its CLI:

# Basic usage with environment variables
npx postofmr

# Check if conditions are met for execution
npx postofmr --check-conditions

# Custom configuration
npx postofmr --version-strategy patch --no-tags

Programmatic Usage

import { HotfixPostMergeHandler } from 'postofmr';

// Basic usage with default configuration
const handler = new HotfixPostMergeHandler();
const result = await handler.execute();

if (result.success) {
  console.log(`Version updated: ${result.versionInfo.newVersion}`);
  console.log(`Tag created: ${result.tagName}`);
} else {
  console.error(`Error: ${result.error}`);
}

GitLab CI Integration

Add to your .gitlab-ci.yml:

hotfix-post-merge:
  stage: post-merge
  image: node:18
  script:
    - npm ci
    - npx postofmr
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH =~ /^TEST_hotfix\/Hotfix-\d{8}$/ && $CI_COMMIT_MESSAGE =~ /Merge branch/
      when: on_success

Configuration

Configuration File

The library supports a local configuration file postofmr-config.json in the current working directory. This provides a convenient way to store project-specific settings.

Configuration Priority (highest to lowest):

1. CLI arguments
2. Environment variables (for specific cases)
3. Config file (postofmr-config.json)
4. Default values

Example postofmr-config.json:

{
  "accessTokenProp": "CUSTOM_TOKEN_VAR",
  "commitMessageTemplate": "chore: version {version} [automated]",
  "createTags": false,
  "versionStrategy": "patch",
  "prereleaseId": "hotfix",
  "gitUserName": "CI Bot",
  "gitUserEmail": "[email protected]",
  "packageJsonPath": "./package.json"
}

Supported Config File Options:

| Option | Type | Description | |--------|------|-------------| | accessTokenProp | string | Environment variable name to read access token from | | commitMessageTemplate | string | Custom commit message template, use {version} placeholder | | createTags | boolean | Whether to create and push git tags | | versionStrategy | string | Version bump strategy: patch, prerelease, or auto | | prereleaseId | string | Prerelease identifier for prerelease versions | | packageJsonPath | string | Path to package.json file | | gitUserName | string | Git user name for commits | | gitUserEmail | string | Git user email for commits |

Special Feature: Dynamic Access Token The accessTokenProp option allows you to specify which environment variable contains your access token:

{
  "accessTokenProp": "MY_CUSTOM_TOKEN"
}

This will read the access token from process.env.MY_CUSTOM_TOKEN instead of the default CI_PUSH_TOKEN.

Environment Variables

The library automatically reads these GitLab CI environment variables:

| Variable | Description | Default | |----------|-------------|---------| | CI_PIPELINE_SOURCE | Pipeline trigger source | - | | CI_COMMIT_BRANCH | Current branch name | main | | CI_COMMIT_MESSAGE | Commit message | - | | CI_PUSH_TOKEN | Git access token | - | | CI_SERVER_HOST | GitLab server hostname | gitlab.com | | CI_PROJECT_PATH | Project path | - | | GITLAB_USER_NAME | Git user name | GitLab CI | | GITLAB_USER_EMAIL | Git user email | [email protected] |

CLI Options

hotfix-post-merge [options]

Options:
  --package-json <path>       Path to package.json (default: ./package.json)
  --branch <name>             Branch name (default: CI_COMMIT_BRANCH)
  --access-token <token>      Git access token (default: CI_PUSH_TOKEN)
  --no-tags                   Don't create and push git tags
  --version-strategy <type>   Version bump strategy: patch, prerelease, auto (default: auto)
  --prerelease-id <id>        Prerelease identifier (default: release)
  --commit-template <msg>     Commit message template, use {version} placeholder
  --git-user-name <name>      Git user name (default: GITLAB_USER_NAME)
  --git-user-email <email>    Git user email (default: GITLAB_USER_EMAIL)
  --check-conditions          Check if current environment meets hotfix conditions
  --help, -h                  Show help message

Programmatic Configuration

import { HotfixPostMergeHandler, HotfixConfig } from 'postofmr';

const config: HotfixConfig = {
  packageJsonPath: './package.json',
  branchName: 'hotfix/fix-123',
  versionStrategy: 'prerelease',
  prereleaseId: 'hotfix',
  createTags: true,
  commitMessageTemplate: 'chore: bump version to {version} [skip ci]',
  gitUserName: 'Hotfix Bot',
  gitUserEmail: '[email protected]'
};

const handler = new HotfixPostMergeHandler(config);

Version Strategies

Auto Strategy (Default)

• Detects if current version has prerelease suffix (e.g., 1.0.0-release.1)
• If prerelease: increments prerelease number (1.0.0-release.2)
• If regular: increments patch version (1.0.1)

Patch Strategy

• Always increments patch version: 1.0.0 → 1.0.1

Prerelease Strategy

• Always increments prerelease version: 1.0.0 → 1.0.0-release.1
• Or: 1.0.0-release.1 → 1.0.0-release.2

Examples

Basic Shell Script Integration

#!/bin/bash
set -e

echo "Starting hotfix post-merge process..."
npx postofmr

if [ $? -eq 0 ]; then
  echo "✅ Hotfix process completed successfully"
else
  echo "❌ Hotfix process failed"
  exit 1
fi

Advanced Node.js Usage

import { HotfixPostMergeHandler } from 'postofmr';

async function handleHotfix() {
  // Check conditions first
  if (!HotfixPostMergeHandler.shouldExecute()) {
    console.log('Hotfix conditions not met, skipping...');
    return;
  }

  const handler = new HotfixPostMergeHandler({
    versionStrategy: 'auto',
    createTags: true,
    commitMessageTemplate: 'chore: bump version to {version} after hotfix merge [skip ci]'
  });

  try {
    const result = await handler.execute();

    if (result.success) {
      console.log('Success!', {
        oldVersion: result.versionInfo.currentVersion,
        newVersion: result.versionInfo.newVersion,
        tag: result.tagName
      });
    } else {
      console.error('Failed:', result.error);
      process.exit(1);
    }
  } catch (error) {
    console.error('Unexpected error:', error);
    process.exit(1);
  }
}

handleHotfix();

GitHub Actions Integration

name: Hotfix Post-Merge
on:
  push:
    branches:
      - 'hotfix/**'

jobs:
  hotfix-post-merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - run: npm ci

      - run: |
          npx postofmr \
            --git-user-name "GitHub Actions" \
            --git-user-email "[email protected]" \
            --access-token "${{ secrets.GITHUB_TOKEN }}"

API Reference

HotfixPostMergeHandler

Main class for handling hotfix operations.

Constructor

constructor(config?: HotfixConfig)

Methods

execute(): Promise

Executes the complete hotfix post-merge process.

static shouldExecute(): boolean

Checks if current CI environment matches hotfix criteria.

Types

HotfixConfig

interface HotfixConfig {
  packageJsonPath?: string;
  remoteUrlPattern?: string;
  accessToken?: string;
  branchName?: string;
  createTags?: boolean;
  versionStrategy?: 'patch' | 'prerelease' | 'auto';
  prereleaseId?: string;
  commitMessageTemplate?: string;
  gitUserName?: string;
  gitUserEmail?: string;
}

HotfixResult

interface HotfixResult {
  success: boolean;
  versionInfo: VersionInfo;
  tagName?: string;
  error?: string;
}

VersionInfo

interface VersionInfo {
  currentVersion: string;
  newVersion: string;
  isPrerelease: boolean;
}

Troubleshooting

Common Issues

1. Permission denied for git operations

   • Ensure CI_PUSH_TOKEN has proper permissions
   • Check repository access rights

2. Branch not found

   • Verify branch exists and is properly checked out
   • Check CI_COMMIT_BRANCH environment variable

3. Version bump fails

   • Ensure package.json exists and is valid
   • Check current working directory

Debug Mode

Add debug logging by setting environment variable:

export DEBUG=hotfix:*
npx postofmr

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run tests: npm test
5. Build: npm run build
6. Submit a pull request

License

MIT License - see LICENSE file for details.