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

Configuration

Add a [jj-gh] table to any jj config layer (global ~/.config/jj/config.toml, repo-local via jj config edit --repo, or a workspace config). jj-gh reads the jj-gh subtree through jj config list, so jj’s own discovery rules (XDG dirs, conf.d includes, --config overrides) apply.

[jj-gh]
default_base_branch = "master"
default_title_source = "head"
pr_fetch_bookmark_template = '"pr-" ++ pr_number ++ "-" ++ pr_slug'
nerdfonts = false

Use jj-gh debug config to inspect the merged config (the token is rendered as ***).

Settings

Authentication

KeyTypeDefaultDescription
gh_askpasscommand (array of strings)unsetHelper that prints a GitHub token on stdout. Prefer this over a plain token. Outranked by --gh-askpass and $GH_ASKPASS.
askpass_timeout_secsinteger20Seconds allowed for an askpass helper.
gh_tokenstringunsetPlain token; less safe. Never logged.

Token source precedence (high to low), resolved outside the config layering:

  1. --gh-askpass CLI flag
  2. $GH_ASKPASS environment variable (shell-split command)
  3. $JJ_GH_TOKEN environment variable
  4. $GH_TOKEN environment variable (matches the gh CLI)
  5. gh_askpass from config
  6. gh_token from config
  7. gh auth token (run gh auth login first to use this)

$JJ_GH_TOKEN is useful when jj-gh needs a different token than the gh CLI. See Authentication.

Behavior

KeyTypeDefaultDescription
default_base_branchstring or unsetunset (None)Fallback base only when neither --base, an ancestor bookmark, nor jj trunk() resolves. If still unresolved, the command errors.
default_remotestring or unsetunset (None)Not deprecated. Fallback for your own pushes and PR head lookups, used only when git’s default remote cannot be auto-resolved; --remote and auto-detection win.
upstream_remotestring or unsetunset (None), effectively upstreamGit remote used as the PR target in fork workflows and as the PR host for fetch. Falls back to upstream when unset.
draftboolfalseOpen new PRs as drafts.
auto_mergeboolfalseEnable auto-merge on newly created PRs.
auto_merge_methodmerge, squash, rebasemergeMerge method when auto-merge is enabled.
auto_stackbooltrueLink created stacked PRs into a GitHub stack.
auto_pushbooltruePush stale bookmarks before pr stack links PRs into a stack.

Templates and editor

KeyTypeDefaultDescription
pr_create_templatejj template string or unsetunsetBody template; also settable via $JJ_GH_TEMPLATE. Aliases are injected; see Templates.
pr_create_template_filepath or unsetunsetMarkdown body template file; also settable via $JJ_GH_TEMPLATE_FILE.
pr_create_title_templatejj template stringdescription.first_line()Renders candidate PR titles (once per commit).
default_title_sourcebase or headbaseWhich commit supplies the default title: oldest (base) or newest (head). Overridden by --title-source.
pr_fetch_bookmark_templatejj template string or unset"pr-" ++ pr_number ++ "/" ++ pr_branchBookmark name template for pr fetch.
pr_log_templatejj template string or unsetbuilt-in PR-aware templateBody of the injected pr_log template used by pr log (and the pr stack log view).
editorcommand (array of strings) or unsetunsetEditor for the frontmatter flow. Falls back to jj’s ui.editor, which jj resolves from $JJ_EDITOR, $VISUAL, $EDITOR. --editor wins over all of these.

Diff previews and icons

KeyTypeDefaultDescription
pr_create_show_diffsbooltrueShow the read-only diff preview while creating a PR body. Overridden by --diffs / --no-diffs.
pr_edit_show_diffsbooltrueShow the diff preview while editing a PR. Overridden by --diffs / --no-diffs.
nerdfontsbooltrueUse Nerd-Font glyphs in the default pr log / pr stack templates. Overridden by --nerdfonts / --no-nerdfonts.

Precedence

Config assembly uses these layers, lowest priority first:

  1. Built-in defaults
  2. jj’s ui.editor (only maps to the editor key)
  3. jj user config (jj config list --user jj-gh)
  4. jj repo config (jj config list --repo jj-gh)
  5. jj workspace config (jj config list --workspace jj-gh)
  6. The file named by $JJ_GH_EXTRA_CONFIG
  7. Environment overlay (JJ_GH_TEMPLATE → pr_create_template, JJ_GH_TEMPLATE_FILE → pr_create_template_file)
  8. CLI flags

So, high to low: CLI flags → env → $JJ_GH_EXTRA_CONFIG → workspace → repo → user → jj ui.editor → built-ins. The main merged config uses jj’s unscoped jj config list jj-gh; the scoped queries exist for the per-layer body-template split below.

pr create body resolution is deliberately split by layer (highest first):

  1. --no-template
  2. -T / --template (jj template string)
  3. --template-file (path)
  4. Repo-layer pr_create_template (repo, workspace, or $JJ_GH_EXTRA_CONFIG)
  5. Repo-layer pr_create_template_file
  6. Auto-detected .github/PULL_REQUEST_TEMPLATE.md (and case variants)
  7. User-layer pr_create_template
  8. User-layer pr_create_template_file

This lets you keep a global default while still picking up each OSS repo’s own pull request template. Full details are in Templates.

JSON schema

jj-gh config schema prints the JSON Schema for the [jj-gh] table on stdout. Point your editor’s JSON-schema support at it to get completion and validation while editing jj config:

jj-gh config schema > ~/.config/jj/jj-gh.schema.json