Introduction
Automated semantic releases and changelog generation for Jujutsu repositories.
Unlike tools built around mutable Git branches (like release-plz or
cargo-release), jj-release is designed natively for jj. It uses jj’s
revset language to walk commit history, operates on movable bookmarks, and uses
a commit-message trigger that fits naturally into the jj workflow.
Installation
| Platform | Command |
|---|---|
| Arch (AUR) | paru -S jj-release |
| Arch (AUR, full) | paru -S jj-release-full |
| Fedora (COPR) | sudo dnf copr enable sayless88/jj-release && sudo dnf install jj-release |
| Fedora (COPR, full) | sudo dnf install jj-release-full |
| Nix | nix run github:saylesss88/jj-release |
| From source | cargo install --git https://github.com/saylesss88/jj-release |
| Cargo Binstall | cargo binstall jj-release |
Requires jj on your PATH.
Features
jj-release uses Cargo features to keep the binary lean, only compile in
support for the forges and publish targets you actually use.
Default Features
The default build includes GitHub and GitLab support:
cargo install jj-release
Forge Features
| Feature | Enables | Requires |
|---|---|---|
github | GitHub releases and PRs via gh | gh CLI |
gitlab | GitLab releases and MRs via glab | glab CLI |
gitea | Gitea releases and PRs via REST API | GITEA_TOKEN |
forgejo | Forgejo/Codeberg via REST API (includes gitea) | FORGEJO_TOKEN |
# Forgejo/Codeberg only, no GitHub or GitLab
cargo install jj-release --no-default-features --features forgejo
Publish Features
| Feature | Enables |
|---|---|
publish-aur | Publishing to the Arch User Repository |
publish-copr | Publishing to Fedora COPR |
# Full build with all forges and publish targets
cargo install jj-release --features full
Library Features
If you’re using jj_release_core as a library:
[dependencies]
# Default: GitHub + GitLab
jj_release_core = "0.9.0"
# Forgejo/Codeberg support
jj_release_core = { version = "0.9.0", features = ["forgejo"] }
# Everything
jj_release_core = { version = "0.9.0", features = ["full"] }
NixOS & Flakes
The flake provides two packages depending on the features you need:
- Default (
default): Includes thegithubandgitlabfeatures. - Full (
jj-release-full): Includes thefullfeature flag.
Try it out without installing:
Run the default package:
nix run github:saylesss88/jj-release
Run the full package:
nix run github:saylesss88/jj-release#jj-release-full
Add to your NixOS configuration via Flakes:
First, add the input to your flake.nix:
# In your flake.nix:
inputs.jj-release.url = "github:saylesss88/jj-release";
Then, in your configuration.nix (assuming inputs is passed via
specialArgs), add your preferred package to environment.systemPackages:
{ inputs, pkgs, ... }: {
environment.systemPackages = [
# Choose ONE of the following:
# 1. For the default build (GitHub/GitLab only):
inputs.jj-release.packages.${pkgs.stdenv.hostPlatform.system}.default
# 2. For the full build:
inputs.jj-release.packages.${pkgs.stdenv.hostPlatform.system}.jj-release-full
];
}
Arch Linux
paru -S jj-release
Fedora
You can install jj-release from the unofficial COPR repository. This
repository provides pre-compiled binaries built automatically for Fedora
systems.
First, enable the repository:
sudo dnf copr enable sayless88/jj-release
Then install the package:
sudo dnf install jj-release
Quick start
The fastest way to set up a new repo:
jj-release init # detects forge, language, workspace: writes release.toml
jj-release validate # confirms everything is ready
# After adding releasable commits:
jj new -m "Release: please"
jj git push --bookmark main
init detects:
- Forge: from the git remote URL (
github.com→ github,gitlab.com→ gitlab,codeberg.org→ forgejo,gitea.com→ gitea) - Language: from files present (
Cargo.toml→ cargo,package.json→ npm,go.mod→ go) - Workspace: reads [workspace.members] from
Cargo.tomland auto-populates member names, paths, and versioning strategy (unified vs independent)
validate checks:
jjidentity configured- Forge CLI available (
gh,glab) cargo-semver-checksdetects breaking API changes & warns if bump should be major version- Runs
cargo publish --dry-run - Manifest readable, version parseable, and in sync with crates.io
- Version tag exists (needed as a baseline)
- Trigger commit present
CARGO_REGISTRY_TOKENset/.cargo/credentials.tomlpresent (if publishing to crates.io)
Your first release
jj-release requires zero configuration for your first release.
If your repository has no existing version tags, jj-release automatically
enters First Release Mode. It will:
- Freeze your
Cargo.tomlversion exactly as it is (e.g.,0.1.0). - Generate a changelog from the very first commit in your repository.
- Publish the release and create your initial version tag.
You do not need to manually create a baseline tag.
Releasing 1.0.0
When you’re ready to release 1.0.0, set force in release.toml:
[bump]
force = "major"
This overrides the automatic bump calculation regardless of commit types. Remove it after the release.
How it works
Add a trigger commit when you’re ready to ship:
jj new -m "Release: please"
jj git push --bookmark main
CI detects the trigger, walks commits back to the last version tag, and classifies them as patch/minor/major using Conventional Commits. API-breaking changes are detected via cargo-semver-checks and can automatically upgrade the bump to major. The version baseline comes from crates.io rather than the local manifest, ensuring the correct bump even when versions have drifted.
A trigger is recognized when any commit reachable from release.bookmark has a
description containing release.trigger (case-sensitive substring match) since
the last version tag. The trigger commit itself is not included in changelog
generation or bump calculation unless its message also matches a Conventional
Commit type.
Accidentally triggering a release with docs: Release: please improve wording
is possible, choose a trigger string unlikely to appear in normal commit
messages.
What a Release Changes
Unless --dry-run is used, jj-release may:
- Modify version manifests and
CHANGELOG.md - Create a release commit and version tag
- Move and push the configured bookmark
- Publish packages to the configured registry
- Create a GitHub, GitLab, or Forgejo release
Run jj-release validate and jj-release --dry-run before enabling it in CI.
Commands
# Show usage and help menu
jj-release --help
# Auto-detect environment and generate a release.toml
jj-release init
# Check everything is ready before releasing
jj-release validate
# Full release pipeline
jj-release
# Dry run, see what would happen without changing anything
jj-release --dry-run
# Run release without publishing to crates.io
jj-release --no-publish
# Force publishing to crates.io even if publish.cargo = false
jj-release -p
# Print the next version that would be released
jj-release next-version
# Override next bump
jj-release --bump major
# Release candidates
jj-release --bump major --pre rc # 1.0.0-rc.1
jj-release --pre rc # 1.0.0-rc.2
jj-release # 1.0.0
# Preview the next changelog section
jj-release changelog
# Prepend the next section to an existing CHANGELOG.md
jj-release changelog -o CHANGELOG.md
# Regenerate the full changelog from all tags (useful for bootstrapping)
jj-release changelog --full -o CHANGELOG.md
# Choose a specific changelog layout (root, per-member, or both)
jj-release changelog --layout both
# Open a PR for review before publishing
jj-release pr
For a more integrated feel, you can add the following to your ~/.config/jj/config.toml:
[aliases]
release = ["util", "exec", "--", "jj-release"]
Now jj release will work to run jj-release.
Local releases
jj-release doesn’t require CI. If you have jj on your PATH and are logged in
to crates.io (cargo login), you can run it directly (Recommended over CI):
jj new -m "Release: please"
jj-release
Running jj-release locally does the full pipeline:
- Scans for the trigger commit since the last version tag
- Walks commits and computes the semver bump from conventional commit types
- Runs pre-flight checks (including
cargo-publish --dry-run) to ensure the release won’t fail midway - Writes a new section to
CHANGELOG.md - Bumps the version in manifest
- Creates a
chore: release vX.Y.Zcommit and tags itvX.Y.Zlocally - Runs the actual
cargo publish - Advances the bookmark and pushes to origin
- Creates a GitHub release (if
create_release = true)
The CARGO_REGISTRY_TOKEN environment variable is only needed in CI where
there’s no credentials file.
Fail-Safe Design: jj-release delays irreversible remote actions (like
git push) until the very end. If a step like cargo publish fails, your
remote git repository remains completely untouched. Because you are using
Jujutsu, you can simply jj abandon the failed local release commit, fix the
underlying issue, and run jj-release again.
Release PRs
If you want to review before it publishes, use the pr subcommand instead:
jj new -m "Release: please"
jj-release pr
This pushes your current bookmark to a release/vX.Y.Z branch and opens a PR
with the changelog preview as the PR body. No version bump, no release commit,
no tag. Merge the PR and CI runs jj-release to do the actual release.
Note
Unlike
release-plz’s continuously maintained release PR,jj-release pris a one-shot preview. No version bump or release commit in the PR itself. If you want a persistent release PR that stays up to date, runjj-release prin CI on every push to main.
CI setup
GitHub Actions
Note
This workflow installs
jjandjj-releaseas prebuilt binaries withcargo binstall, so it runs in about a minute plus your build time. If a prebuilt binary isn’t available for the runner, binstall falls back to compiling from source, which takes much longer.
Add this workflow to your consumer repo at .github/workflows/release.yml:
name: Release
on:
push:
branches:
- main
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
actions: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
# Still needed: `cargo publish` and cargo-semver-checks run during the release.
- name: Install Rust toolchain
uses: dtolnay/rust-toolchain@stable
- name: Cache cargo registry
uses: actions/cache@v4
with:
path: |
~/.cargo/registry
~/.cargo/git
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
restore-keys: |
${{ runner.os }}-cargo-
- name: Install cargo-binstall
uses: cargo-bins/cargo-binstall@main
- name: Install jj, jj-release and cargo-semver-checks
run:
cargo binstall --no-confirm --disable-telemetry jj-cli jj-release
cargo-semver-checks
- name: Attach jj to colocated git repo
run: jj git init --colocate
- name: Run release
run: jj-release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
- name: Build release binaries
if: success()
run: |
tag=$(git describe --tags --abbrev=0)
gh workflow run release_binaries.yml -f tag="$tag"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Note
The last step triggers
release_binaries.yml(see Cargo Binstall support below). If you don’t publish prebuilt binaries, delete that step and removeactions: writefrompermissions.
Cargo Binstall support for your Crate
Add the following to your Cargo.toml:
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }{ archive-suffix }"
pkg-fmt = "tgz"
Create a .github/workflows/release_binaries.yml:
name: Release binaries
# Builds prebuilt binaries for `cargo binstall` and attaches them to a release.
#
# Triggers:
# - release: published -> only fires if the release was created with a PAT or
# GitHub App token. Releases made with GITHUB_TOKEN
# don't trigger other workflows.
# - workflow_dispatch -> run it by hand, or call it with
# `gh workflow run release_binaries.yml -f tag=vX.Y.Z`
# from your release workflow (needs `actions: write`).
on:
release:
types: [published]
workflow_dispatch:
inputs:
tag:
description: "Release tag to build and upload to (e.g. v2.0.0)"
required: true
unlocked:
description: "Skip --locked (only for old tags with a stale Cargo.lock)"
type: boolean
default: false
permissions:
contents: write
jobs:
build:
strategy:
fail-fast: false
matrix:
include:
- { target: x86_64-unknown-linux-musl, os: ubuntu-latest }
- { target: aarch64-apple-darwin, os: macos-latest }
- { target: x86_64-apple-darwin, os: macos-latest }
- { target: x86_64-pc-windows-msvc, os: windows-latest }
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
with:
# Build the tagged source, whichever way the workflow was started.
ref: ${{ inputs.tag || github.event.release.tag_name }}
- uses: dtolnay/rust-toolchain@stable
with:
targets: ${{ matrix.target }}
# --locked fails the build if Cargo.lock doesn't match Cargo.toml, so the
# binary uses exactly the dependency versions you committed. A published
# release and a normal manual run both get it; only an explicit
# `unlocked` opt-out skips it.
- name: Build
run:
cargo build --release --target ${{ matrix.target }} ${{
inputs.unlocked != true && '--locked' || '' }}
- name: Package and upload
shell: bash
env:
GH_TOKEN: ${{ github.token }}
TAG: ${{ inputs.tag || github.event.release.tag_name }}
TARGET: ${{ matrix.target }}
run: |
# Single-crate repos: the package name is read from Cargo. In a
# workspace, set `name` to your binary crate by hand.
name=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].name')
ext=""; [[ "$TARGET" == *windows* ]] && ext=".exe"
cp "target/$TARGET/release/$name$ext" .
tar czf "$name-$TARGET.tar.gz" "$name$ext"
gh release upload "$TAG" "$name-$TARGET.tar.gz" --clobber
Configuration
Drop a release.toml in your repo root, or run jj-release init to generate
one automatically. All fields are optional, defaults work for most GitHub + Rust
projects out of the box:
manifest_backend = "cargo" # manifest format: cargo, npm, go
[release]
trigger = "Release: please" # commit message substring that kicks off a release
tag_prefix = "v" # prefix for version tags, e.g. v1.2.3
bookmark = "main" # bookmark to advance after release
forge = "github" # github, gitlab, forgejo, gitea, or none
create_release = false # create a release on the forge after tagging
forge_url = "" # base URL for self-hosted forges
[bump]
# force = "minor" # override commit analysis: "major", "minor", or "patch"
# pre = "rc" # release pre-releases on this channel: 1.0.0-rc.1, -rc.2, …
features_bump_patch_before_1_0 = false # before 1.0, release features as patches (0.4.1 → 0.4.2)
[publish]
cargo = false # set to true to publish to crates.io
cargo_flags = [] # extra flags forwarded to `cargo publish`
semver_checks = true # run cargo-semver-checks before publishing
semver_checks_upgrade_major = false # also upgrade pre-1.0 crates to a breaking bump
[changelog]
enabled = true # write a CHANGELOG.md entry on each release
file = "CHANGELOG.md" # path to the changelog file
strict = true # drop unmapped/unformatted commits (false = "Other Changes")
link_headers = false # link each version heading to a forge compare view
layout = "root" # "root", "per-member", or "both" (workspaces)
# [aur]
# Required: The exact name of your package on the AUR
# package = "my-cli-tool"
# Optional: Override the default Git URL.
# Defaults to ssh://aur@aur.archlinux.org/{package}.git
# repo = "ssh://aur@aur.archlinux.org/custom-repo-name.git"
# [copr]
# Required: your COPR project as owner/project
# project = "your-username/my-cli-tool"
# Required: path to the spec, relative to the repo root
# spec = "packaging/rust-my-cli-tool.spec"
# Optional: wait for the COPR build to finish (default: false)
# wait = true
manifest_backend is a top-level key, so it must come before the first
[table] header. TOML puts any key written after a header inside that table.
The forgejo and gitea forges are behind Cargo features of the same name.
Publishing
By default, jj-release only handles versioning, changelogs, tags, and forge
releases. To automatically publish to crates.io, explicitly enable it in your
configuration:
[publish]
cargo = true
Publishing can also be skipped per-run with --no-publish without editing
release.toml, useful for testing the release pipeline or in scripts that
handle publishing separately. --publish-cargo (-p) does the opposite.
Pre-releases are never sent to the AUR or COPR. Distro packages are only updated for stable versions.
Per-run overrides
These flags override release.toml for a single run, so there’s nothing to
change and change back:
| Flag | Overrides | Example |
|---|---|---|
--bump <LEVEL> | bump.force | --bump major releases 1.0.0 from 0.x |
--pre <CHANNEL> | bump.pre | --pre rc releases 1.0.0-rc.1, then -rc.2, … |
--layout <LAYOUT> | changelog.layout | --layout both |
--no-publish / -p | publish.cargo | --no-publish |
Versioning before 1.0
Before 1.0.0, Cargo treats the minor version as the breaking position, and
jj-release follows it: a breaking change (feat!:, BREAKING CHANGE:)
bumps the minor version (0.10.0 → 0.11.0), never the major. Moving to 1.0.0
is always your call:
jj-release --bump major
Features bump the minor version by default (0.4.21 → 0.5.0). For a library
other crates depend on, release them as patches instead, so dependents
requiring "0.4" pick them up without a requirement change:
[bump]
features_bump_patch_before_1_0 = true
Pre-releases
--pre <channel> (or bump.pre) releases the next pre-release instead of a
stable version. A run without it promotes the latest pre-release to stable:
jj-release --bump major --pre rc # 0.11.0 → 1.0.0-rc.1
jj-release --pre rc # 1.0.0-rc.2
jj-release --pre beta # refused: beta sorts below rc
jj-release # 1.0.0
Moving up a channel (alpha → beta → rc) restarts the number at .1.
Workspaces
jj-release init detects a Cargo workspace and writes this section for you:
[workspace]
enabled = true
versioning = "independent" # "unified": one version for every member
[[workspace.members]]
name = "globset"
path = "crates/globset"
tag_prefix = "globset-" # tags look like globset-0.4.22
[[workspace.members]]
name = "ignore"
path = "crates/ignore"
tag_prefix = "ignore-"
depends_on = ["globset"] # members it depends on: sets publish order
With independent versioning, each member is released from its own tags and only when its files changed. When a member’s new version no longer satisfies another member’s requirement on it, that dependent is released too.
Version bumps in other files
jj-release bumps version = "..." in a flake.nix at the repo root
automatically. For anything else, such as install snippets in a README, add a
replacement:
[[replacements]]
file = "README.md"
search = 'my-crate = "[0-9.]+"'
replace = 'my-crate = "{{version}}"'
exactly_one = true # fail unless the pattern matches exactly once
replace can use {{version}}, {{crate_name}}, and {{date}}.
Changelog Configuration
You can customize how jj-release parses your commits and maps them to the Keep
a Changelog format. By default, these commit types are included:
| Commit type | Changelog section |
|---|---|
feat | Added |
refactor | Changed |
perf | Performance |
deprecate, deprecated | Deprecated |
remove, removed | Removed |
fix | Fixed |
bug | Bug |
security | Security |
docs | Documentation |
Anything else (chore, ci, test, unknown types, and messages that aren’t
Conventional Commits) is dropped, or collected under “Other Changes” with
strict = false. Breaking changes are marked **BREAKING** in their section.
Add these options to your release.toml to customize the behavior:
[changelog]
enabled = true
file = "CHANGELOG.md"
# Add emojis to the changelog headers
emoji_headers = true
# If true (default), commits that do not strictly match Conventional Commits
# or your prefix_mapping are silently dropped from the changelog.
# If false, unformatted commits are collected in an "Other Changes" section.
strict = false
# Commits to leave out of the changelog, matched as a whole word at the start
# of the message: "fix" excludes `fix: …`, `fix(cli): …` and `fix!: …`, but not
# "fixed a typo". Use "chore(deps)" to exclude only that scope.
exclude_prefixes = ["chore", "ci", "test", "WIP:"]
# Override specific default emojis (keys must match the exact Header name)
[changelog.emoji_mapping]
Added = "🚀"
Fixed = "✅️"
Bug = "🔥"
Performance = "⚡️"
Testing = "🧪"
# Map conventional commit types to custom Keep a Changelog headers.
# A mapped type is included even with strict = true. Custom headers appear
# after the standard ones, in alphabetical order.
[changelog.prefix_mapping]
revert = "Reverted"
test = "Testing"
Conventional Commits
jj-release follows the
Conventional Commits spec to determine
the version bump. It natively supports standard Angular types alongside a
dedicated bug type:
| Commit type | Bump | Changelog Header |
|---|---|---|
feat: | minor | Added |
fix: | patch | Fixed |
bug: | patch | Bug |
refactor: | patch | Changed |
perf: | patch | Performance |
docs: | No release | Documentation |
feat!: or BREAKING CHANGE footer | major | Breaking |
chore:, docs:, test:, etc. | No release | Dropped by default |
deprecate:, deprecated: | No release | Deprecated |
chore:, test:, ci: | No release | Dropped by default |
The highest bump across all commits since the last tag wins. Scoped commits are
preserved in the changelog. feat(cli): add init subcommand renders as
**(cli)** add init subcommand under ### Added
Note
chore:,docs:,style:,test:,ci:, andbuild:commits do not trigger a release. If your only changes since the last tag are in these categories, jj-release will exit with “No releasable commits”. Either add afeat:orfix:commit, or force a bump inrelease.toml:[bump] force = "patch"Remove
forceafter the release so future versions are computed automatically.
Changelogs
jj-release follows the Keep a Changelog format.
Each release prepends a new section to CHANGELOG.md:
# Preview the next changelog section
jj-release changelog
# Prepend the next section(s) to the configured changelog file(s)
jj-release changelog -w
# Prepend the next section to a specific file (root layout only)
jj-release changelog -o NOTES.md
# Regenerate the full changelog from all tags (useful for bootstrapping)
jj-release changelog --full -w
# Override to a specific layout from the command-line (root, per-member, or both)
jj-release changelog --layout both
-w (--write) writes to [changelog].file (default CHANGELOG.md): at the
repository root, in each workspace member’s directory, or both, depending on
layout. -o writes to one explicit path, so it only
works with the root layout; -o and -w can’t be combined.
Note
Without
--full,-wprepends the new section. With--full, it overwrites the file with the regenerated history.
If the manifest version hasn’t been bumped past the latest tag, the preview
renders the pending changes as ## [Unreleased]. Once released, the section
gets its version and the release date.
Basic Changelog Example
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## Unreleased
## [0.2.0] - 2026-09-08
### Added
- **(cli)** add init subcommand
- add wallpaper cycling support
### Fixed
- prevent daemon crash on empty directory
Scopes (feat(cli): ...) are shown in bold, and breaking changes (feat!: ...)
are marked BREAKING.
Emoji headers and compare links
With emoji_headers = true and link_headers = true:
## [Unreleased](https://github.com/saylesss88/jj-release/compare/v0.2.0...HEAD)
## [0.2.0](https://github.com/saylesss88/jj-release/compare/v0.1.0...v0.2.0) - 2026-09-08
### ✨ Added
- **(cli)** add init subcommand
- add wallpaper cycling support
### 🛠️ Fixed
- prevent daemon crash on empty directory
Compare links work for GitHub, GitLab, Codeberg/Forgejo, and Gitea. Self-hosted
instances need [release].forge_url set.
Changelog Configuration
By default, these commit types are included:
| Commit type | Section |
|---|---|
feat | Added |
refactor | Changed |
perf | Performance |
deprecate, deprecated | Deprecated |
fix | Fixed |
bug | Bug |
docs | Documentation |
style, chore, build, ci and test are dropped in strict mode (the
default). Any other type can be mapped to a section with prefix_mapping.
[changelog]
enabled = true
file = "CHANGELOG.md"
# Add emojis to the section headers
emoji_headers = true
# Link version headings to the forge's compare page
link_headers = true
# "root" (default), "per-member", or "both". See Workspace layouts below.
layout = "per-member"
# If true (default), commits that don't parse as Conventional Commits, or
# whose type isn't mapped, are dropped. If false, they're collected in an
# "Other Changes" section.
strict = false
# Commit types or raw message prefixes to always exclude.
exclude_prefixes = ["chore", "ci", "test", "WIP:"]
# Override default emojis (keys are section names).
[changelog.emoji_mapping]
Added = "🚀"
Fixed = "✅️"
Bug = "🔥"
Performance = "⚡️"
Testing = "🧪"
# Map commit types to sections. Built-in types are mapped automatically.
[changelog.prefix_mapping]
revert = "Reverted"
security = "Security"
test = "Testing"
Custom sections appear after the standard ones, sorted alphabetically.
Workspace layouts
In a workspace, layout controls where changelogs are written:
layout | Writes |
|---|---|
"root" | One CHANGELOG.md at the repository root (default) |
"per-member" | One CHANGELOG.md in each member’s directory |
"both" | Each member’s CHANGELOG.md plus one at the root |
Which commits go where
A member’s changelog contains the commits that changed files in that member’s
directory. The commit message’s scope doesn’t matter: feat(cli): lands in
lib/CHANGELOG.md if it only touched files under lib/.
- A commit touching two members appears in both changelogs.
- A commit touching only files outside every member (CI, README, the workspace
Cargo.toml) appears in no member changelog. Use"both"with unified versioning to keep a record of those in the root changelog. - A member at the repository root (a root package, like
ripgrepin its own workspace) doesn’t include the other members’ directories, even though they sit inside it.
To check what a member’s next changelog will contain, run the same query
jj-release uses:
jj log -r 'v0.10.0..@ & files(root:"lib")'
The root changelog with "both"
-
Unified versioning: the root changelog gets a normal section listing every commit in the release, including changes outside any member.
-
Independent versioning: the root changelog gets one named section per released member:
## globset [0.5.0] - 2026-11-02 ### Added - **(glob)** support brace expansion ## ignore [0.4.35] - 2026-11-02 ### Dependencies - Updated `globset` to 0.5.0
A member located at the repository root shares the root changelog instead of getting a second file in the same place.
Dependency updates
In an independent workspace, when a member’s new version no longer satisfies a
dependent’s version requirement, the dependent is released too, with a patch
bump. Its changelog section lists the dependency change under
### Dependencies, even if it has no commits of its own.
Previewing and writing workspace changelogs
With "per-member" or "both", the preview prints each file under a header so
you can check them before writing:
jj-release changelog
==> CHANGELOG.md <==
## [0.11.0] - 2026-11-02
...
==> lib/CHANGELOG.md <==
## [0.11.0] - 2026-11-02
...
==> cli/CHANGELOG.md <==
...
# Prepend the next sections to every configured file
jj-release changelog -w
# Regenerate every configured file from history
jj-release changelog --full -w
Note
The preview doesn’t include
### Dependenciesnotes or members released only because of a dependency update; those are added during the release itself. With independent versioning,--fullregenerates each member’s changelog but not the aggregated root changelog.
Version replacements
jj-release can automatically update version strings in arbitrary files (like
your README.md, installation scripts, or flake.nix) during the release
process.
Native Nix Flake Support
If your repository contains a flake.nix file in the root directory with a
standard version = "..." declaration, jj-release will automatically detect
it and bump the version alongside your project manifest.
This behavior is native and requires zero configuration.
Custom Replacements
You can configure additional regex-based search-and-replace operations across
other project files by adding an array of [[replacements]] tables to your
release.toml.
The replace field supports built-in template variables that are substituted
before the regex substitution occurs.
| Variable | Description | Example Output |
|---|---|---|
{{version}} | The new semantic version being released. | 1.2.3 |
{{crate_name}} | The name of the primary crate. | my_crate |
{{date}} | Today’s date in YYYY-MM-DD format. | 2026-09-24 |
Configuration Example
# Update installation instructions in README.md
[[replacements]]
file = "README.md"
search = 'jj-release = ".*"'
replace = 'jj-release = "{{version}}"'
# Update version constants in source code, using capture groups
# for complex lines. Use native TOML braces {{1}} for regex groups.
[[replacements]]
file = "lib/src/manifest.rs"
search = 'version\s*=\s*"[^"]+"'
# NOTE: Native TOML braces become standard braces in regex replacement
replace = 'version = "${{1}}{{version}}${{3}}"'
Forges
jj-release supports multiple forges for release creation and PR/MR opening:
| Forge | forge = | CLI required | Release | PR/MR | Status |
|---|---|---|---|---|---|
| GitHub (default) | "github" | gh | ✓ | ✓ | ✓ tested |
| GitLab | "gitlab" | glab | ✓ | ✓ (MR) | ✓ tested |
| Forgejo/Codeberg | "forgejo" | none (REST) | ✓ | ✓ | ✓ tested on Codeberg, release creation not yet supported (see note) |
| Gitea | "gitea" | none (REST) | ✓ | ✓ | implemented, untested |
| None | "none" | – | – | – | – |
For GitLab, set forge_url if using a self-hosted instance:
[release]
forge = "gitlab"
forge_url = "https://gitlab.example.com"
For Forgejo/Codeberg, set forge_url to your instance and provide a token:
[release]
forge = "forgejo"
forge_url = "https://codeberg.org"
export FORGEJO_TOKEN=your-token
For Gitea, set forge_url to your instance and provide a token:
[release]
forge = "gitea"
forge_url = "https://gitea.com"
export GITEA_TOKEN=your-token
Note
Forgejo/Codeberg and Gitea: tagging, pushing, and PR creation all work correctly.
create_release = trueis not yet supported. The release API requires annotated git tags butjjcreates lightweight tags. Keepcreate_release = false.
The token needs repository scope, create one at
https://codeberg.org/user/settings/applications.
| Forge | Authentication |
|---|---|
| GitHub | gh auth login locally or GITHUB_TOKEN in GitHub Actions |
| GitLab | glab auth login locally or the token/env mechanism used by glab |
| Forgejo | FORGEJO_TOKEN and forge_url |
| Gitea | GITEA_TOKEN and forge_url |
Workspaces
jj-release supports Rust workspaces with two versioning strategies. Run
jj-release init to auto-detect which one your workspace uses.
Unified Versioning
All members share a single version from [workspace.package]. Every member bumps together on each release:
[workspace]
enabled = true
versioning = "unified" # or "independent"
[[workspace.members]]
name = "mylib"
path = "lib"
publish = true
[[workspace.members]]
name = "mycli"
path = "cli"
publish = true
depends_on = ["mylib"] # publish lib before cli
Note
jj-release initfills independs_onfrom yourCargo.tomlfiles. If you add a dependency between members later, add it todepends_onas well.
Cross-member dependency versions are updated automatically during the release.
You do not need to manually update Cargo.toml dependency versions between
workspace members before releasing.
For example, the version requirement in this local dependency will
automatically be kept in sync:
[dependencies]
jj_release_core = { path = "../lib", version = "0.7.0" }
Independent Versioning
Each member has its own version and only bumps when commits touched its path. Members get their own tag prefix:
[workspace]
enabled = true
versioning = "independent"
[[workspace.members]]
name = "mylib"
path = "lib"
publish = true
tag_prefix = "mylib-v" # creates tags like mylib-v0.5.0
[[workspace.members]]
name = "mycli"
path = "cli"
publish = true
tag_prefix = "v"
depends_on = ["mylib"]
Members are published in dependency order. mylib before mycli. So crates.io
has time to index the library before the CLI tries to depend on it.
jj-release --dry-run
Current version: 0.7.0
[dry-run] Independent workspace release:
[dry-run] Would publish in order:
- mylib (lib) 0.4.0 (no changes, skipping)
- mycli (cli) 0.7.0 → 0.8.0 (tag: mycli-v0.8.0)
Cross-member dependency versions are updated automatically during the release.
You do not need to manually update Cargo.toml dependency versions between
workspace members before releasing.
Other languages
jj-release supports multiple manifest formats via manifest_backend:
| Language | manifest_backend = | Version file | Publish command |
|---|---|---|---|
| Rust | "cargo" (default) | Cargo.toml | cargo publish |
| JavaScript | "npm" | package.json | npm publish |
| Golang | "go" | tag-only | – |
Note
npm and Golang support is implemented but not yet battle-tested in production. Feedback welcome if you use
jj-releasewith these languages.
Exit codes
jj-release uses distinct exit codes so CI scripts can distinguish failure
modes:
| Code | Meaning |
|---|---|
| 0 | Success, or no trigger found (nothing to do) |
| 2 | Missing or invalid configuration |
| 3 | Missing required CLI tool (gh, glab) |
| 101 | General release failure |
Exit code 1 is reserved for unexpected panics. All handled errors use the codes
above. The Silent exit state passes through an arbitrary code for cases where
the error was already reported upstream.
AUR
jj-release can automatically update your AUR package after a successful
crates.io and Forge release. This step runs at the very end of the pipeline to
ensure the new source tarball is fully available for checksum calculation.
Prerequisites
- Feature flag:
jj-releasemust be built with thepublish-aur(orfull) feature:cargo install jj-release --features publish-aur. The AUR, COPR, and Nix packages include it already. - Tools:
gitandcurlmust be on yourPATH.makepkgis optional (see below), so this works from any Linux distro or macOS. - Authentication: your machine needs SSH access to
aur@aur.archlinux.org, the same setup you’d use to push to the AUR by hand.
Configuration
Add the [aur] table to your release.toml:
[publish.aur]
# Required: The exact name of your package on the AUR
package = "my-cli-tool"
# fail_on_error = false
# Optional: Override the default Git URL.
# Defaults to ssh://aur@aur.archlinux.org/{package}.git
# repo = "ssh://aur@aur.archlinux.org/custom-repo-name.git"
fail_on_errorcontrols whether an AUR failure aborts the release or just warns. Setfail_on_error = trueif you want a failure to be treated as fatal.
Pipeline Execution
When AUR publishing is enabled, jj-release executes the following sequence
after all other release steps succeed:
-
Clones your AUR package repository into a temporary directory.
-
Sets
pkgverin thePKGBUILDto the new version and resetspkgrelto1. -
Downloads each remote source with
curland recomputes its checksums (sha256sumsand/orb2sums). Downloads are retried briefly, since crates.io can take a few seconds to serve a newly published crate. -
Regenerates
.SRCINFOwithmakepkg --printsrcinfo. Ifmakepkgisn’t available, it updates the version, source, and checksum fields in.SRCINFOdirectly. -
Commits the changes as
Update to <version>and pushes to the AUR.
If the AUR package is already at the new version, this step is skipped, so rerunning after a partial failure is safe.
Limitations
- Only
sha256sumsandb2sumsare supported. Other checksum arrays and architecture-specific sources (source_x86_64) produce a clear error. - If you edit the
PKGBUILDby hand, regenerate.SRCINFOyourself before pushing. Withoutmakepkg,jj-releaseonly updates version-related fields.
Dry run
jj-release --dry-run shows what version the AUR package and COPR spec would be
bumped to, but does not clone, download, or modify anything. No SSH access or
network access is required for the dry run.
Fedora COPR
jj-release can build a source RPM for each release and submit it to your
COPR project. It runs at the end of the
pipeline, after the crates.io publish, since the RPM is built from the published
crate.
Prerequisites
- Feature flag:
jj-releasemust be built with thepublish-copr(orfull) feature:cargo install jj-release --features publish-copr. - A Fedora (or other RPM-based) machine with:
sudo dnf install copr-cli rpm-build cargo-rpm-macros curl tar xz cargo
- COPR API access: log in at
copr.fedorainfracloud.org/api, copy
the configuration block, and save it to
~/.config/copr. - An existing COPR project with the chroots you want to build for.
The spec file
Keep your RPM spec in your repository. jj-release builds from a temporary copy
with the new version and never modifies the original. The spec must have:
%global crate <crate-name>: used to download the published.crate- a
Version:line: replaced with the new version SourceN: vendor.tar.xz: the vendored dependencies, since COPR builders have no network access
A spec generated with rust2rpm and adjusted for vendoring works as is:
Source0: %{crates_source}
Source1: vendor.tar.xz
%prep
%autosetup -n %{crate}-%{version} -p1 -a 1
%cargo_prep -v vendor
Remove %generate_buildrequires / %cargo_generate_buildrequires, since
dependencies come from the vendor tarball instead of Fedora packages. To build
with Cargo features, pass them to the macros, e.g. %cargo_build -f full and
%cargo_install -f full.
Note
If you want the local
.specversion to stay in sync with each release, setupdate_local = truein your[publish.copr]config:[publish.copr] project = "sayless88/jj-release" spec = "copr/rust-jj-release.spec" update_local = true fail_on_error = falseWithout this, only the temporary copy used to build the SRPM is updated, the spec file in your repository is left unchanged.
fail_on_errorcontrols whether an COPR failure aborts the release or just warns. Setfail_on_error = trueif you want a failure to be treated as fatal.
Configuration
Add a [copr] table to your release.toml:
[publish.copr]
# Required: your COPR project as owner/project
project = "your-username/my-cli-tool"
# fail_on_error = false
# Required: path to the spec, relative to the repo root
spec = "packaging/rust-my-cli-tool.spec"
# Optional: wait for the COPR build to finish (default: false)
# wait = true
What it does
After all other release steps succeed, jj-release:
- Copies the spec to a temporary directory and sets
Version:to the new version. - Downloads the published
.cratefrom crates.io withcurl, retrying briefly while the CDN catches up. - Extracts it, runs
cargo vendor, and packs the result asvendor.tar.xz. - Builds a source RPM with
rpmbuild -bs. - Submits it with
copr-cli build. By default it doesn’t wait for the build; setwait = trueto follow it and have failures reported.
A COPR failure is reported as a warning rather than failing the release, since the crates.io publish, tag, and forge release have already happened.
Limitations
- Pre-release versions (e.g.
1.0.0-rc.1) are not supported yet, since RPM versions can’t contain-. - Skipped when
publish.cargo = false, since the RPM is built from the crates.io release. - Skipped for workspaces with independent versioning.
Checking your setup
jj-release validate checks that the required tools are installed, the spec has
the required fields, cargo-rpm-macros is available, and copr-cli is
authenticated. The same checks run automatically before every release, so a
broken setup fails before anything is published.
jj-release --dry-run lists the COPR submission a release would make, without
building or submitting anything.
Recovering from a failed release
If a release fails midway through (e.g., cargo publish fails due to registry
validation), you can cleanly revert the entire pipeline using Jujutsu’s
operation log:
- Find the operation right before you ran
jj-release(look for theRelease: pleasecommit):
jj op log
- Restore the repo to that operation:
jj op restore <operation_hash>
- Discard the mutated files (like
Cargo.tomlbumps) from your working copy:
jj restore
Note
jj-releaserunscargo publish --dry-runas a pre-flight check, but this only validates local compilation. Server-side registry rejections (like invalid URLs or missing permissions) will still cause the pipeline to fail during the final push.
Fixing commit messages after a release (Immutable Commits)
If you need to fix a typo in a commit message after a release is finalized (which marks the commit as immutable), rewriting the message will detach the Git tag. Because changelog generators rely on Git tags to group history, you must re-anchor the tag to the new timeline before regenerating the changelog.
- Rewrite the commit message:
jj --ignore-immutable desc -r <commit_rev> -m 'fix: your new message'
(Note: use single quotes ' if your message contains backticks so your shell
doesn’t execute them). 2. Find the new release commit hash: Because history is
rewritten, the release commit generated a new hash. Find it using jj log. 3.
Re-anchor the release tag (i.e. The commit chore: release vX.Y.Z):
jj tag set vX.Y.Z -r <NEW_RELEASE_HASH> --allow-move
(Note: the further back in history you go, the more tags you’ll have to re-anchor) 4. Regenerate your changelog. The generator will now traverse the corrected timeline and parse the updated messages.
rm CHANGELOG.md
jj-release changelog --full -o CHANGELOG.md
- Push/Force-push the corrected history. Since you altered public history, force- push the updated branch and tag back to your remote.
# Push the corrected bookmark (no force need if jj handles the move)
jj git push
# Force-push each re-anchored tag via git directly
# (jj git push doesn't support --force)
git push origin vX.Y.Z --force
Or if you have multiple tags to re-anchor, push them all:
jj git push # pushes the bookmark
# then for each re-anchored tag:
git push origin v0.1.0 --force
git push origin v0.2.0 --force
# etc.
Force-pushing is generally considered bad practice in collaborative projects since others may have fetched the old tags. For a solo project it’s fine, just keep this in mind..
Fixing commit messages after a release
If you need to fix a typo in a commit message after a release is finalized (which marks the commit as immutable), rewriting the message will detach the Git tag. Because changelog generators rely on Git tags to group history, you must re-anchor the tag to the new timeline before regenerating the changelog.
- Rewrite the commit message:
jj --ignore-immutable desc -r <commit_rev> -m 'fix: your new message'
(Note: use single quotes ' if your message contains backticks so your shell
doesn’t execute them). 2. Find the new release commit hash: Because history is
rewritten, the release commit generated a new hash. Find it using jj log. 3.
Re-anchor the release tag (i.e. The commit chore: release vX.Y.Z):
jj tag set vX.Y.Z -r <NEW_RELEASE_HASH> --allow-move
(Note: the further back in history you go, the more tags you’ll have to re-anchor) 4. Regenerate your changelog. The generator will now traverse the corrected timeline and parse the updated messages.
rm CHANGELOG.md
jj-release changelog --full -o CHANGELOG.md
- Push/Force-push the corrected history. Since you altered public history, force- push the updated branch and tag back to your remote.
# Push the corrected bookmark (no force need if jj handles the move)
jj git push
# Force-push each re-anchored tag via git directly
# (jj git push doesn't support --force)
git push origin vX.Y.Z --force
Or if you have multiple tags to re-anchor, push them all:
jj git push # pushes the bookmark
# then for each re-anchored tag:
git push origin v0.1.0 --force
git push origin v0.2.0 --force
# etc.
Force-pushing is generally considered bad practice in collaborative projects since others may have fetched the old tags. For a solo project it’s fine, just keep this in mind..