Post-Merge

Automated version management and Git operations for CI/CD pipelines. A modern CLI tool built with Commander.js for seamless GitLab CI/CD automation.

Features

🚀 Automatic Version Management

• Smart version bumping with patch, prerelease, and auto strategies
• Semantic version detection and increment
• Support for prerelease identifiers

🏷️ Git Operations

• Automated tag creation and pushing
• Commit message templating with version placeholders
• Remote repository synchronization

⚙️ GitLab CI Integration

• Built-in condition checking for merge triggers
• Automatic GitLab CI configuration generation
• Environment variable integration

🔧 Flexible Configuration

• CLI arguments, config files, and environment variables
• Dynamic access token resolution
• Customizable Node.js Docker images

Installation

npm install post-merge

Quick Start

Basic Usage

# Execute post-merge automation
npx post-merge

# Check if conditions are met
npx post-merge check

# Initialize GitLab CI configuration
npx post-merge init

Commands

| Command | Description | |---------|-------------| | post-merge | Execute the main post-merge automation process | | post-merge init | Initialize GitLab CI configuration and scripts | | post-merge check | Check if current environment meets execution conditions |

Command Options

# Main command options
npx post-merge --version-strategy patch --no-tags
npx post-merge --commit-template "chore: bump to {version} [skip ci]"

# Init command options
npx post-merge init --branch-pattern "^hotfix/.*$"
npx post-merge init --nodejs-image-url node:18

Configuration

Three-Tier Configuration System

Priority: CLI args > Environment vars > Config file > Defaults

Config File (post-merge-config.json)

{
  "accessTokenProp": "CUSTOM_TOKEN_VAR",
  "nodejsImageUrl": "NODEJS_IMAGE_ENV_VAR",
  "versionStrategy": "auto",
  "commitMessageTemplate": "chore: version {version} [automated]",
  "createTags": true,
  "prereleaseId": "release",
  "gitUserName": "CI Bot",
  "gitUserEmail": "[email protected]"
}

Environment Variables

| Variable | Description | |----------|-------------| | CI_PIPELINE_SOURCE | Should be 'push' for hotfix detection | | CI_COMMIT_BRANCH | Branch pattern matching (e.g., TEST_hotfix/Hotfix-YYYYMMDD) | | CI_COMMIT_MESSAGE | Should contain 'Merge branch' for trigger | | CI_PUSH_TOKEN | Git access token with write permissions | | GITLAB_USER_NAME | Git user name for commits | | GITLAB_USER_EMAIL | Git user email for commits |

GitLab CI Integration

Generated Configuration

Run npx post-merge init to generate:

# .gitlab-ci.yml
post-merge-job:
  stage: post-merge
  image: node:18
  before_script:
    - git config --global user.name "${GITLAB_USER_NAME}"
    - git config --global user.email "${GITLAB_USER_EMAIL}"
  script:
    - chmod +x scripts/post-merge.sh
    - ./scripts/post-merge.sh
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH =~ /^TEST_hotfix\/Hotfix-\d{8}$/ && $CI_COMMIT_MESSAGE =~ /Merge branch/
      when: on_success

Version Strategies

• auto (default): Detects current version type and increments accordingly
• patch: Always increments patch version (1.0.0 → 1.0.1)
• prerelease: Always increments prerelease (1.0.0 → 1.0.0-release.1)

Programmatic Usage

import { PostMergeHandler } from 'post-merge';

const handler = new PostMergeHandler({
  versionStrategy: 'auto',
  createTags: true,
  commitMessageTemplate: 'chore: bump to {version}'
});

const result = await handler.execute();
if (result.success) {
  console.log(`Version: ${result.versionInfo.newVersion}`);
}

License

MIT