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.
npm install --global versioningsRequires Node.js >= 18.
# 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-featureSee the Setup Guide for a complete walkthrough.
| 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 toversionings release.
- 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
plancommand - 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.
| 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.
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
- Node.js >= 18
- npm
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 filessrc/
├── 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)
__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)
MIT