auto-release

A Hvigor plugin for automatic version management and release workflow in HarmonyOS projects. Supports MCP (Model Context Protocol) for AI agent integration.

Features

• 🔄 Automatic Version Calculation: Generates version numbers based on Conventional Commits
• 📝 Changelog Generation: Creates changelogs following Keep a Changelog format
• 🌿 Multi-branch Strategy: Supports main, feature, release, and hotfix branches
• 📦 oh-package.json5 Support: Automatically updates HarmonyOS package files
• 🏷️ Git Tag Management: Creates and pushes version tags automatically
• 🤖 MCP Support: AI agents can integrate via Model Context Protocol

Installation

ohpm install auto-release

Or via npm:

npm install auto-release --registry=https://repo.harmonyos.com/npm/

Usage

As Hvigor Plugin

Configure in your hvigorfile.ts:

import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { createReleasePlugin } from 'auto-release';

export default {
  system: hapTasks,
  plugins: [
    createReleasePlugin({
      tagPrefix: 'v',
      pushTag: true,
      changelogFile: 'CHANGELOG.md',
      packageFile: 'oh-package.json5'
    })
  ]
}

Hvigor Commands

# Full release process (auto version)
hvigorw --mode module -p product=default -p module=Module@default -p dryRun=true talRelease

# Show next version only (no release)
hvigorw --mode module -p product=default -p module=Module@default -p dryRun=true talVersion

# Generate changelog only (no release)
hvigorw --mode module -p product=default -p module=Module@default -p dryRun=true talChangelog

# Initialize changelog from git history
hvigorw --mode module -p product=default -p module=Module@default -p dryRun=true talInit

MCP Integration (AI Agents)

AI agents can integrate with auto-release via the Model Context Protocol (MCP).

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "auto-release": {
      "command": "npx",
      "args": ["-y", "auto-release-mcp"]
    }
  }
}

MCP Tools Available

| Tool | Description | |------|-------------| | release | Execute full release process | | get_next_version | Preview next version without changes | | generate_changelog | Generate changelog content | | init_changelog | Initialize changelog from git history | | get_current_version | Get current version info | | list_commits | List commits since last release |

MCP Resources

• auto-release://config - Default configuration values
• auto-release://version-strategy - Version bump strategy documentation

Version Strategy

Conventional Commits

The plugin analyzes commit messages following Conventional Commits:

| Commit Type | Version Bump | |-------------|--------------| | feat: | Minor (0.1.0 → 0.2.0) | | fix: | Patch (0.1.0 → 0.1.1) | | BREAKING CHANGE: | Major (0.1.0 → 1.0.0) |

Example commits:

feat: add user authentication
fix: resolve login timeout issue
feat!: completely redesign API (BREAKING CHANGE)

Branch Strategy

| Branch | Version Format | Example | |--------|----------------|---------| | main/master | X.Y.Z | 1.0.0 | | feature/<tag> | X.Y.Z-.N | 1.0.0-oauth.1 | | release/<tag> | X.Y.Z-rc.N | 1.0.0-rc.1 | | hotfix/* | X.Y.Z-hotfix.N | 1.0.0-hotfix.1 |

Configuration Options

interface ReleaseConfig {
  // Git tag prefix (default: 'v')
  tagPrefix: string;

  // Push tag to remote (default: true)
  pushTag: boolean;

  // Changelog file path (default: 'CHANGELOG.md')
  changelogFile: string;

  // Package file path (default: 'oh-package.json5')
  packageFile: string;

  // Release commit message template (default: 'chore: release {version}')
  releaseCommitMessage: string;

  // Allow release on dirty working directory (default: false)
  allowDirty: boolean;

  // Skip git hooks (default: false)
  noVerify: boolean;

  // Preview mode (default: false)
  dryRun: boolean;

  // Remote name for pushing (default: 'origin')
  remote: string;

  // Branch patterns configuration
  branches: {
    main: string[];     // ['main', 'master']
    feature: string[];  // ['feature/*', 'feat/*']
    release: string[];  // ['release/*', 'rc/*']
    hotfix: string[];   // ['hotfix/*', 'fix/*']
  };
}

Release Process

The release process follows these steps:

1. Verify git repository status
2. Check working directory is clean
3. Detect current branch type
4. Get latest version tag
5. Parse commits since last release
6. Calculate next version
7. Generate changelog
8. Update oh-package.json5
9. Update CHANGELOG.md
10. Commit changes
11. Create git tag
12. Push tag to remote

Changelog Format

Generated changelogs follow Keep a Changelog:

## [1.0.0] - 2024-01-15

### Breaking Changes

- **api**: Removed deprecated endpoints (abc1234)

### Added

- **auth**: Add OAuth2 authentication support (def5678)
- **ui**: Add dark mode toggle (ghi9012)

### Fixed

- **login**: Resolve session timeout issue (jkl3456)

Plugin API

The plugin implements the standard Hvigor plugin interface:

import type { HvigorPlugin, HvigorNode } from '@ohos/hvigor';

const plugin: HvigorPlugin = createReleasePlugin({
  tagPrefix: 'v'
});

// The plugin registers the following tasks:
// - 'talRelease': Full release process
// - 'talVersion': Show next version
// - 'talChangelog': Generate changelog
// - 'talInit': Initialize changelog

Programmatic Usage

import { ReleaseManager, DEFAULT_CONFIG } from 'auto-release';

const manager = new ReleaseManager({
  ...DEFAULT_CONFIG,
  tagPrefix: 'v',
  dryRun: true
});

// Preview next version
const versionInfo = await manager.getNextVersion();
console.log(versionInfo.version);

// Execute release
const result = await manager.release();
if (result.success) {
  console.log(`Released: ${result.version}`);
}

Development

# Install dependencies
npm install --registry=https://repo.harmonyos.com/npm/

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

Publishing to NPM

# Build and publish
npm run build
npm publish

# Or with public access
npm publish --access public

Requirements

• Node.js >= 18.0.0
• Git
• @ohos/hvigor >= 6.0.0 (peer dependency, optional for MCP usage)

License

MIT