@blendsdk/lockstep
Advanced tools
A comprehensive monorepo package management tool that maintains synchronized versions across all packages (lockstep versioning) with flexible CI/CD integration.
A comprehensive monorepo package management tool that maintains synchronized versions across all packages (lockstep versioning) with flexible CI/CD integration.
CHANGELOG.md and root RELEASE_NOTES.mdnpm install -g @blendsdk/lockstep
# or
yarn global add @blendsdk/lockstep
# or
pnpm add -g @blendsdk/lockstep
npm install --save-dev @blendsdk/lockstep
# or
yarn add -D @blendsdk/lockstep
# or
pnpm add -D @blendsdk/lockstep
# Bump patch version for all packages
lockstep version --type patch
# Automatically determine version from conventional commits
lockstep version --type auto
# Publish all packages to latest
lockstep publish --tag latest
# Publish to next tag (for development releases)
lockstep publish --tag next
# Version with CI skip flag
lockstep version --type auto --ci
# Publish and push git changes
lockstep publish --tag latest --git-push
Bumps versions of all packages in lockstep and optionally commits/tags.
lockstep version --type <patch|minor|major|auto> [options]
Options:
--type <patch|minor|major|auto> - Type of version bump (required)--ci - Add [skip ci] to commit message--no-git-commit - Skip git commit and tag operations--no-changelog - Skip AI changelog generation during the bumpExamples:
lockstep version --type patch
lockstep version --type minor --ci
lockstep version --type major --no-git-commit
lockstep version --type auto
lockstep version --type auto --ci
lockstep version --type patch --no-changelog
By default a version bump also generates changelog and release-notes files and folds them into the release commit. See AI Changelog & Release Notes below.
Generates a per-package CHANGELOG.md and a root RELEASE_NOTES.md for the current release,
without bumping any versions. Useful for previewing notes or regenerating them on demand.
lockstep changelog [options]
Options:
--dry-run - Print what would be generated; write nothing--verbose - Print detailed progress and token usageExamples:
lockstep changelog
lockstep changelog --dry-run
lockstep changelog --verbose
Publishes all packages in dependency order with branch-prefixed dist-tags.
lockstep publish --tag <dist-tag> [options]
Options:
--tag <dist-tag> - Distribution tag for publishing (required)--access <public|restricted> - NPM access level (default: public)--dry - Perform a dry run without publishing--git-push - Push git changes and tags after publish--provenance - Generate npm provenance attestations (requires supported CI)Examples:
lockstep publish --tag latest
lockstep publish --tag alpha
lockstep publish --tag beta --dry
lockstep publish --tag latest --access restricted
lockstep publish --tag alpha --git-push
lockstep publish --tag latest --provenance
When using --type auto, lockstep analyzes conventional commit messages since the last tag:
feat: commits → minor version bumpfix:, docs:, style:, refactor:, test:, chore: → patch version bumpBREAKING CHANGE or !: → major version bump# Analyzes commits and determines appropriate version bump
lockstep version --type auto
Non-main branches automatically get prefixed dist-tags:
main, master) → latest or specified tag{branch-name}-{tag}# On main branch
lockstep publish --tag latest # → publishes as "latest"
# On feature-branch
lockstep publish --tag alpha # → publishes as "feature-branch-alpha"
Lockstep can write your changelog for you. It inspects the conventional commits since the last
release tag, attributes each commit to the package(s) it touched, and asks an LLM to draft the
entries — producing a Keep a Changelog-style CHANGELOG.md per
package plus a reader-friendly RELEASE_NOTES.md at the repo root.
Generation runs automatically during lockstep version (opt out with --no-changelog), or on
demand via lockstep changelog.
The SDKs are optional dependencies — install whichever provider you use:
npm install openai # OpenAI (primary)
npm install @anthropic-ai/sdk # Anthropic (fallback)
Configure via environment variables:
| Variable | Purpose | Default |
|---|---|---|
OPENAI_API_KEY | Enables the OpenAI provider (tried first) | — |
ANTHROPIC_API_KEY | Enables the Anthropic provider (fallback) | — |
LOCKSTEP_OPENAI_MODEL | Override the OpenAI model | gpt-4o-mini |
LOCKSTEP_ANTHROPIC_MODEL | Override the Anthropic model | claude-haiku-4-5-20251001 |
OpenAI is tried first; if it is unavailable or errors, Anthropic is used.
Changelog generation is best-effort and is designed to never stop a release:
version-triggered failure degrades to a warning; the bump, commit, and tag still complete.Only commit metadata is sent to the LLM — commit subjects/types, scopes, and changed file paths (capped). File contents and diffs are never transmitted, and API keys are never logged or written to any generated file.
npm provenance attaches a signed,
publicly verifiable record linking each published package to the source commit and CI build that
produced it. Enable it with --provenance:
lockstep publish --tag latest --provenance
Provenance is opt-in and has requirements enforced by npm:
--provenance never blocks the publish.repository field required. Every package that publishes with provenance must declare a
repository field in its package.json. Lockstep validates this before publishing anything
and aborts the whole run if a provenance-enabled package is missing it, so a partial publish can't
strand the monorepo.permissions: id-token: write.A single package can also opt in via "publishConfig": { "provenance": true } in its
package.json, independent of the flag.
Lockstep works out of the box but can be configured for specific needs:
Automatically detects your package manager:
pnpm-lock.yaml → pnpmyarn.lock → yarnpackage-lock.json → npmBy default, searches for packages in:
packages/ directory (recursively)Supports any monorepo structure with package.json files.
You can also use lockstep programmatically in Node.js:
import { Lockstep } from '@blendsdk/lockstep';
const lockstep = new Lockstep({
root: process.cwd(),
packagesDirs: ['packages'],
packageManager: 'yarn'
});
// Version all packages
await lockstep.version({
type: 'auto',
skipCi: true,
noGitCommit: false
});
// Publish all packages
await lockstep.publish({
tag: 'latest',
access: 'public',
dry: false,
gitPush: true
});
Example workflow for automated releases:
name: Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
packages: write
id-token: write # required for npm provenance
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
- run: npm install -g @blendsdk/lockstep
- name: Version packages
run: lockstep version --type auto --ci
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Publish packages
run: lockstep publish --tag latest --git-push --provenance
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Lockstep versioning is ideal for:
For a detailed analysis of when to use lockstep versioning, see our comprehensive guide.
package.json filesMIT © TrueSoftware B.V.
Contributions are welcome! Please read our contributing guidelines first.
Made with ❤️ by TrueSoftware B.V.
FAQs
A comprehensive monorepo package management tool that maintains synchronized versions across all packages (lockstep versioning) with flexible CI/CD integration.
The npm package @blendsdk/lockstep receives a total of 18 weekly downloads. As such, @blendsdk/lockstep popularity was classified as not popular.
We found that @blendsdk/lockstep demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.