just-release
Advanced tools
The simplest way to release version-synchronized packages on GitHub.
just-release does one thing well: it makes releasing packages with synchronized versions as simple as running a single command.
This tool is opinionated by design. It doesn't try to support every weird release workflow - it supports the best one:
just-release handles the full lifecycle: version bumping, changelogs, release PRs, publishing to registries (npm, crates.io), and creating GitHub releases.
If this matches your workflow (and it should), just-release will make your life easier. If you need something else, this probably isn't the tool for you.
pnpm add -D just-release
Or run directly with npx:
npx just-release
By default, just-release runs in dry-run mode when not in a CI environment:
pnpm just-release
This will show you what would happen without making any actual changes.
Set CI=1 to execute the release process:
CI=1 GITHUB_TOKEN=$GITHUB_TOKEN pnpm just-release
package.json, Cargo.toml, and/or go.mod at the repo root. Discovers all packages across all detected ecosystems.release: X.Y.Z commit → latest vX.Y.Z tag → 0.0.0feat: → minor version bumpfix: → patch version bumpBREAKING CHANGE: or feat!: → major version bumpchore:, docs: → no releaseCHANGELOG.md in each affected packagerelease/YYYY-MM-DDpackage.json, Cargo.toml; Go versions are purely git tags)release: X.Y.Zpackage.json at rootpnpm-workspace.yaml or package.json workspaces fieldversion in all package.json filesCargo.toml at root[workspace] members patternsversion.workspace = true inheritanceversion in Cargo.toml files (preserving formatting and comments)go.mod at rootgo.work use directivesIf your repo contains multiple ecosystems (e.g., a TypeScript CLI with a Rust native module), just-release discovers and processes all of them. Every package shares the same synchronized version.
CI - Set to 1 to run in live mode (default: dry-run)GITHUB_TOKEN - Required for creating/updating PRs (only in live mode)<type>: <subject>
<body>
<footer>
feat: - New feature (minor version bump)fix: - Bug fix (patch version bump)perf: - Performance improvement (patch version bump)docs: - Documentation changes (no version bump)chore: - Maintenance tasks (no version bump)test: - Test changes (no version bump)Add ! after the type or include BREAKING CHANGE: in the footer:
feat!: remove deprecated API
BREAKING CHANGE: The old API has been removed. Use the new API instead.
Important: Your repository (or organization) must allow GitHub Actions to create pull requests, or the workflow will fail.
Set this once for all repositories in your organization:
Once enabled at the organization level, this setting will apply to all repositories in the organization (unless individually overridden).
If you're not using organization-level settings, configure each repository individually:
Note: If your organization disables this setting, the repository-level option will be grayed out. You must enable it at the organization level first.
Create .github/workflows/release.yml:
name: Release
on:
push:
branches:
- main
permissions:
contents: write
pull-requests: write
jobs:
release:
runs-on: ubuntu-latest
# Skip if this is a release commit (squash merge) or merge of a release branch (regular merge)
if: >-
!startsWith(github.event.head_commit.message, 'release:') &&
!(startsWith(github.event.head_commit.message, 'Merge') && contains(github.event.head_commit.message, 'release/'))
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Required to get all commits
- uses: actions/setup-node@v4
with:
node-version: 'lts/*'
- run: npx just-release
env:
CI: 1
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
When just-release runs in post-release mode (i.e., the current commit is a release: X.Y.Z commit), it automatically:
vX.Y.Z tagYou just need to provide the right environment variables and ensure your project builds before just-release runs.
Below are publish workflow examples for each ecosystem.
just-release detects your package manager (pnpm/yarn/npm) and runs the appropriate publish command. It skips private packages automatically.
Authentication: Set NODE_AUTH_TOKEN or NPM_TOKEN as an environment variable. If neither is set, npm publishing is skipped.
Create .github/workflows/publish.yml:
name: Publish
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: write
id-token: write
jobs:
publish:
runs-on: ubuntu-latest
if: >-
startsWith(github.event.head_commit.message, 'release:') ||
(startsWith(github.event.head_commit.message, 'Merge') && contains(github.event.head_commit.message, 'release/'))
permissions:
contents: write
id-token: write
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 'lts/*'
cache: 'pnpm'
registry-url: 'https://registry.npmjs.org'
- run: pnpm install
- run: pnpm build
# just-release handles npm publish + GitHub release
- run: npx just-release
env:
CI: 1
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Option 1: Trusted Publishing (Recommended)
Trusted publishing uses OIDC — no npm tokens required. Works with npmjs.org or any registry that supports it.
publish.yml (optional but recommended)Important:
package.json must have a repository field matching your GitHub repo exactly:
https://github.com/Owner/repo-name (no git+ prefix, no .git suffix)Aeolun, not aeolun)Option 2: NPM Token
NPM_TOKEN in your GitHub repository settingsjust-release runs cargo publish for each non-private crate in workspace order.
Authentication: Set CARGO_REGISTRY_TOKEN as an environment variable. If not set, Rust publishing is skipped.
Create .github/workflows/publish.yml:
name: Publish
on:
push:
branches:
- main
permissions:
contents: write
jobs:
publish:
runs-on: ubuntu-latest
if: >-
startsWith(github.event.head_commit.message, 'release:') ||
(startsWith(github.event.head_commit.message, 'Merge') && contains(github.event.head_commit.message, 'release/'))
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: actions/setup-node@v4
with:
node-version: 'lts/*'
# just-release handles cargo publish + GitHub release
- run: npx just-release
env:
CI: 1
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
Note: If your crates have internal dependencies, just-release publishes them in workspace order so dependencies are available on crates.io before dependents are published.
Go modules don't need an explicit publish step. The go tool resolves modules directly from git tags, and just-release creates vX.Y.Z tags via the GitHub release.
Create .github/workflows/publish.yml:
name: Publish
on:
push:
branches:
- main
permissions:
contents: write
jobs:
publish:
runs-on: ubuntu-latest
if: >-
startsWith(github.event.head_commit.message, 'release:') ||
(startsWith(github.event.head_commit.message, 'Merge') && contains(github.event.head_commit.message, 'release/'))
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 'lts/*'
# Creates GitHub release with vX.Y.Z tag
- run: npx just-release
env:
CI: 1
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Users can then install your module with:
go get github.com/your-org/your-module@v1.2.3
GitHub limits PR body text to 65,536 characters. For repositories with many commits since the last release, the PR description is progressively truncated in three tiers:
This ensures the PR always stays within GitHub's limit while showing as much detail as possible.
just-release automatically adapts to your repository structure:
pnpm-workspace.yaml or package.json workspaces are found, all workspace packages are bumped to the same versionCargo.toml has a [workspace] section with members, all crates are bumped togethergo.work exists, all modules listed in use directives are tracked togetherpackage.json and Cargo.toml will have all packages from both ecosystems versioned together.origin remote pointing to GitHubpackage.json, Cargo.toml, or go.modISC
FAQs
Automated monorepo release tool with conventional commits
We found that just-release demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.
Security News
OpenSSF has issued a high-severity advisory warning open source developers of an active Slack-based campaign using impersonation to deliver malware.