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

Authentication

jj-gh needs a GitHub token to read and create PRs. Tokens are handled as secrets: they are never logged, and jj-gh debug auth reports whether a token resolves without printing it.

Use an OAuth token or a classic personal access token. Some GitHub API data used by jj-gh is gated behind permissions that fine-grained tokens cannot request, so some features may not work with fine-grained tokens. See issue #167.

OAuth token (simplest): log in with the browser flow, then no further configuration is needed. jj-gh falls back to gh auth token when no higher-priority source is set.

gh auth login

Classic personal access token:

Repository accessScope needed
Private reposrepo (full control)
Public repos onlypublic_repo is sufficient for pr create and pr fetch

Fine-grained personal access token, with access to the target repositories:

PermissionLevelUsed by
MetadataReadevery API call (always required)
Commit StatusesReadUsed to show GitHub Actions status for PRs in jj pr log
ContentsReadpr create (resolving the base branch ref), pr fetch (fetching refs/pull/<n>/head via gix)
Pull requestsRead and writepr create (list + create, enable auto-merge), pr fetch (get)
IssuesRead and writepr create when applying labels (GitHub labels go through the Issues API)

If you do not apply labels, you can drop the Issues permission. GitHub treats PRs as Issues for the purposes of applying labels.

Token source precedence

jj-gh uses the first source that yields a token, from highest to lowest priority:

PrioritySourceNotes
1--gh-askpass <CMD>CLI flag; command prints the token on stdout. Outranks everything else.
2$GH_ASKPASSEnvironment variable containing an askpass command; shell-split and run.
3$JJ_GH_TOKENUse this when jj-gh needs a different token than the gh CLI.
4$GH_TOKENMatches the gh CLI convention.
5gh_askpass in configAskpass command from any [jj-gh] config layer.
6gh_token in configPlain text token; less safe than an askpass helper.
7gh auth tokenFalls back to the GitHub CLI, so gh auth login is enough to get started.

Flags and environment variables always override gh_askpass/gh_token set in config files. An askpass helper must exit successfully and print exactly one token to stdout; helpers time out after askpass_timeout_secs (default 20, override with --askpass-timeout).

Examples

Use the gh CLI’s authentication:

gh auth login

Use an environment token (one-off or in your shell profile):

export JJ_GH_TOKEN='<token>'   # jj-gh only
export GH_TOKEN='<token>'      # follows the gh convention

Use an askpass helper from the environment or CLI:

export GH_ASKPASS='op read op://Vault/GitHub/token'
jj pr log --gh-askpass 'op read op://Vault/GitHub/token'

Configure a helper (or a plain token) in any jj config layer:

[jj-gh]
gh_askpass = ["op", "read", "op://Vault/GitHub/token"]  # preferred
# gh_token = "<token>"  # plain text, less safe
askpass_timeout_secs = 20

See Configuration for where [jj-gh] settings can live.