post-merge/README.md

A reusable library for handling post-merge operations including version bumping and git tagging

# 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

```bash
npm install post-merge
```

## Quick Start

### Basic Usage

```bash
# 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

```bash
# 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`)

```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": "ci@company.com"
}
```

### 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:

```yaml
# .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

```typescript
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