Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

jj-release: semantic releases & changelogs for jj

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

PlatformCommand
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
Nixnix run github:saylesss88/jj-release
From sourcecargo install --git https://github.com/saylesss88/jj-release
Cargo Binstallcargo 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

FeatureEnablesRequires
githubGitHub releases and PRs via ghgh CLI
gitlabGitLab releases and MRs via glabglab CLI
giteaGitea releases and PRs via REST APIGITEA_TOKEN
forgejoForgejo/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

FeatureEnables
publish-aurPublishing to the Arch User Repository
publish-coprPublishing 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 the github and gitlab features.
  • Full (jj-release-full): Includes the full feature 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.toml and auto-populates member names, paths, and versioning strategy (unified vs independent)

validate checks:

  • jj identity configured
  • Forge CLI available (gh, glab)
  • cargo-semver-checks detects 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_TOKEN set/.cargo/credentials.toml present (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:

  1. Freeze your Cargo.toml version exactly as it is (e.g., 0.1.0).
  2. Generate a changelog from the very first commit in your repository.
  3. 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:

  1. Scans for the trigger commit since the last version tag
  2. Walks commits and computes the semver bump from conventional commit types
  3. Runs pre-flight checks (including cargo-publish --dry-run) to ensure the release won’t fail midway
  4. Writes a new section to CHANGELOG.md
  5. Bumps the version in manifest
  6. Creates a chore: release vX.Y.Z commit and tags it vX.Y.Z locally
  7. Runs the actual cargo publish
  8. Advances the bookmark and pushes to origin
  9. 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 pr is 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, run jj-release pr in CI on every push to main.

CI setup

GitHub Actions

Note

This workflow installs jj and jj-release as prebuilt binaries with cargo 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 remove actions: write from permissions.

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:

FlagOverridesExample
--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 / -ppublish.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 typeChangelog section
featAdded
refactorChanged
perfPerformance
deprecate, deprecatedDeprecated
remove, removedRemoved
fixFixed
bugBug
securitySecurity
docsDocumentation

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 typeBumpChangelog Header
feat:minorAdded
fix:patchFixed
bug:patchBug
refactor:patchChanged
perf:patchPerformance
docs:No releaseDocumentation
feat!: or BREAKING CHANGE footermajorBreaking
chore:, docs:, test:, etc.No releaseDropped by default
deprecate:, deprecated:No releaseDeprecated
chore:, test:, ci:No releaseDropped 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:, and build: 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 a feat: or fix: commit, or force a bump in release.toml:

[bump]
force = "patch"

Remove force after 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, -w prepends 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.

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 typeSection
featAdded
refactorChanged
perfPerformance
deprecate, deprecatedDeprecated
fixFixed
bugBug
docsDocumentation

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:

layoutWrites
"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 ripgrep in 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 ### Dependencies notes or members released only because of a dependency update; those are added during the release itself. With independent versioning, --full regenerates 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.

VariableDescriptionExample 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:

Forgeforge =CLI requiredReleasePR/MRStatus
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 = true is not yet supported. The release API requires annotated git tags but jj creates lightweight tags. Keep create_release = false.

The token needs repository scope, create one at https://codeberg.org/user/settings/applications.

ForgeAuthentication
GitHubgh auth login locally or GITHUB_TOKEN in GitHub Actions
GitLabglab auth login locally or the token/env mechanism used by glab
ForgejoFORGEJO_TOKEN and forge_url
GiteaGITEA_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 init fills in depends_on from your Cargo.toml files. If you add a dependency between members later, add it to depends_on as 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:

Languagemanifest_backend =Version filePublish command
Rust"cargo" (default)Cargo.tomlcargo publish
JavaScript"npm"package.jsonnpm 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-release with these languages.

Exit codes

jj-release uses distinct exit codes so CI scripts can distinguish failure modes:

CodeMeaning
0Success, or no trigger found (nothing to do)
2Missing or invalid configuration
3Missing required CLI tool (gh, glab)
101General 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

  1. Feature flag: jj-release must be built with the publish-aur (or full) feature: cargo install jj-release --features publish-aur. The AUR, COPR, and Nix packages include it already.
  2. Tools: git and curl must be on your PATH. makepkg is optional (see below), so this works from any Linux distro or macOS.
  3. 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_error controls whether an AUR failure aborts the release or just warns. Set fail_on_error = true if 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:

  1. Clones your AUR package repository into a temporary directory.

  2. Sets pkgver in the PKGBUILD to the new version and resets pkgrel to 1.

  3. Downloads each remote source with curl and recomputes its checksums (sha256sums and/or b2sums). Downloads are retried briefly, since crates.io can take a few seconds to serve a newly published crate.

  4. Regenerates .SRCINFO with makepkg --printsrcinfo. If makepkg isn’t available, it updates the version, source, and checksum fields in .SRCINFO directly.

  5. 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 sha256sums and b2sums are supported. Other checksum arrays and architecture-specific sources (source_x86_64) produce a clear error.
  • If you edit the PKGBUILD by hand, regenerate .SRCINFO yourself before pushing. Without makepkg, jj-release only 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

  1. Feature flag: jj-release must be built with the publish-copr (or full) feature: cargo install jj-release --features publish-copr.
  2. A Fedora (or other RPM-based) machine with:
   sudo dnf install copr-cli rpm-build cargo-rpm-macros curl tar xz cargo
  1. COPR API access: log in at copr.fedorainfracloud.org/api, copy the configuration block, and save it to ~/.config/copr.
  2. 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 .spec version to stay in sync with each release, set update_local = true in your [publish.copr] config:

[publish.copr]
project = "sayless88/jj-release"
spec = "copr/rust-jj-release.spec"
update_local = true
fail_on_error = false

Without this, only the temporary copy used to build the SRPM is updated, the spec file in your repository is left unchanged.

fail_on_error controls whether an COPR failure aborts the release or just warns. Set fail_on_error = true if 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:

  1. Copies the spec to a temporary directory and sets Version: to the new version.
  2. Downloads the published .crate from crates.io with curl, retrying briefly while the CDN catches up.
  3. Extracts it, runs cargo vendor, and packs the result as vendor.tar.xz.
  4. Builds a source RPM with rpmbuild -bs.
  5. Submits it with copr-cli build. By default it doesn’t wait for the build; set wait = true to 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:

  1. Find the operation right before you ran jj-release (look for the Release: please commit):
jj op log
  1. Restore the repo to that operation:
jj op restore <operation_hash>
  1. Discard the mutated files (like Cargo.toml bumps) from your working copy:
jj restore

Note

jj-release runs cargo publish --dry-run as 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.

  1. 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
  1. 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.

  1. 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
  1. 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..