Versionings — Semantic Release Platform for Git

CLI tool that automates semantic versioning workflows for Git repositories. Bumps versions, creates branches and tags, and optionally pushes changes and opens pull requests on supported SCM platforms.

Installation

npm install --global versionings

Requires Node.js >= 18.

Quick Start

# Create a configuration file
versionings init

# Preview what will happen (dry-run)
versionings plan --semver=patch --branch=my-feature

# Execute the versioning workflow
versionings release --semver=patch --branch=my-feature

See the Setup Guide for a complete walkthrough.

Commands

| Command | Description | Mutates Repo? | |---------|-------------|---------------| | init | Interactive config wizard | No | | validate | Check config and environment | No | | plan | Dry-run: show execution plan | No | | release | Execute versioning workflow | Yes | | rollback | Revert last operation | Yes | | doctor | Diagnose environment | No | | changelog | Generate changelog from commits | No |

See the CLI Reference for full details on each command, parameters, and examples.

Backward compatibility: Running versionings --semver=<type> --branch=<name> without a subcommand is equivalent to versionings release.

Features

• 6 branching strategies (default, trunk-based, git-flow, release-branch, hotfix, maintenance)
• 6 SCM platforms (GitHub, GitHub Enterprise, Bitbucket, Bitbucket Server, GitLab, Azure DevOps)
• Conventional Commits parsing with --semver=auto
• Changelog generation from commit history
• Interactive and non-interactive modes
• Config Provenance (--print-config)
• Dry-run with plan command
• Automatic rollback on failure
• JSON output for CI (--json)
• Structured JSON logging with operation IDs and actor metadata
• Concurrency lock to prevent parallel releases
• Action trace with step-level timing

See the documentation for details on each feature.

Exit Codes

| Code | Name | Description | |------|------|-------------| | 0 | SUCCESS | Successful completion | | 1 | CONFIG_ERROR | Configuration error | | 2 | DIRTY_TREE | Uncommitted changes | | 3 | INVALID_ARGS | Invalid CLI arguments | | 4 | ARTIFACT_CONFLICT | Branch or tag already exists | | 5 | COMMAND_FAILED | Git/npm command failed | | 6 | NETWORK_ERROR | Network error | | 7 | INCOMPLETE_ROLLBACK | Rollback could not complete | | 8 | NO_OPERATION | Nothing to rollback | | 9 | USER_CANCELLED | User cancelled operation | | 10 | POLICY_VIOLATION | Branch policy violated | | 11 | NO_CONVENTIONAL_COMMITS | No conventional commits for auto-bump |

See the Failure Matrix for causes, error examples, and remediation steps.

Documentation

Full documentation is available in the docs/ directory:

• Setup Guide — Installation, configuration, and first release
• Configuration Reference — All config fields, sources, and examples
• CLI Reference — Commands, flags, and output formats
• Failure Matrix — Exit codes with causes and solutions
• Branch Strategy Cookbook — 6 branching strategies with examples
• SCM Provider Guide — Platform setup and PR/MR automation
• CI/CD Examples — GitHub Actions, GitLab CI, Azure Pipelines, Bitbucket Pipelines
• Changelog Format Guide — Conventional Commits and changelog configuration
• Operational Hardening Guide — Structured logging, operation IDs, and concurrency lock
• Migration Guide — Upgrading between versions

Development

Prerequisites

• Node.js >= 18
• npm

Commands

npm install          # Install dependencies
npm run build        # Bundle via esbuild + emit type declarations
npm test             # Run all tests (unit, property, integration, e2e)
npm run typecheck    # Type-check without emitting
npm run lint         # Lint all source and test files

Project Structure

src/
├── cli/               # CLI entry point, command router, subcommands
│   ├── version.ts     # Entry point (compiles to out/dist/index.js)
│   ├── command.router.ts
│   ├── interaction.manager.ts
│   └── commands/      # init, validate, plan, release, rollback, doctor, changelog
├── core/              # Pipeline, executor, errors, rollback, reporter
│   ├── pipeline.ts    # Workflow orchestration
│   ├── executor.ts    # Shell command execution (Promise-based, DI)
│   ├── errors.ts      # Exit codes (0–11) and VersioningsError
│   ├── rollback.ts    # Rollback manager
│   ├── reporter.ts    # JSON / human-readable output
│   ├── structured.logger.ts  # Structured JSON logging
│   ├── lock.manager.ts       # Concurrency lock
│   ├── action.tracer.ts      # Step timing trace
│   └── actor.resolver.ts     # Git user / CI actor metadata
├── config/            # Configuration loading, merging, validation
├── scm/               # SCM provider abstraction and PR/MR creation
│   ├── providers/     # GitHub, GitLab, Bitbucket, Azure DevOps
│   └── ...
├── branching/         # Branching strategies and policy checker
│   ├── strategies/    # default, trunk-based, git-flow, release, hotfix, maintenance
│   └── ...
├── versioning/        # Conventional commits, auto-bump, changelog
└── utils/             # Shared utilities (ANSI colors, helpers)

Test Structure

__tests__/
├── unit/              # Module-level tests with mocks (mirrored by domain)
│   ├── cli/
│   ├── core/
│   ├── config/
│   ├── scm/
│   ├── branching/
│   ├── versioning/
│   └── utils/
├── properties/        # Property-based tests (fast-check, 100+ iterations each)
│   ├── core/
│   ├── config/
│   ├── scm/
│   ├── branching/
│   └── versioning/
├── integration/       # Full pipeline with real git repos (no mocks)
├── e2e/               # CLI as child process with real git repos
└── helpers/           # Test utilities (repo fixture creation)

License

MIT