GitHub / Pull Request Integration

See a worktree’s PR status and CI, and act on it — merge, mark-ready, re-run failed jobs, copy failure logs — without leaving Prowl.

Keywords:githubpull requestPRCIchecksmergemark readyre-runfailing jobscode hostgh cli

Related: command-palette · repositories-and-worktrees · diff-view · settings

What it is#

For git repositories hosted on GitHub, Prowl fetches the pull request associated with a worktree’s branch and exposes its status and actions. It works through the gh CLI, so it uses your existing gh auth — Prowl never handles tokens itself.

If a repository has multiple GitHub remotes, Prowl checks each remote for a PR on the worktree branch. origin is preferred, upstream comes next, and other named remotes are used alphabetically, so fork-based worktrees can show upstream PRs without changing origin or restarting the app. A returned PR’s head repository must match one of the repository’s configured GitHub remotes; PRs from unrelated forks that happen to use the same branch name are ignored.

Prowl also watches the repository’s git config while the app is running. When remote URLs are added, removed, or changed, it refreshes the repository’s PR state and code-host label automatically; if the repository no longer has a GitHub remote, stale PR badges are cleared.

What it shows#

• PR number, title, state (open/closed/merged), draft status.
• Additions/deletions, author, base/head branches.
• Review decision (approved / changes requested / pending).
• CI status: a rollup of all checks (success / failure / in-progress / expected / skipped) with failing/success counts and per-check detail URLs.
• Merge readiness: Prowl evaluates blockers in order — merge conflicts, changes requested, failed checks, other non-mergeable states.
• Merge queue: for repos that use GitHub merge queues, an open PR waiting in the queue shows a brown Queued state in the sidebar and badges, and the PR checks popover adds an “In merge queue” row with its position and estimated time remaining.

PR status can surface as a badge on the worktree and as a summary in the command palette. The PR #N tag in a sidebar row is a link — click it to open the pull request in the browser; right-click the row → Open Pull Request does the same (falling back to the repository page when no PR URL is known).

Actions (via Command Palette, when a PR exists)#

Open the Command Palette (⌘P) on a worktree that has a PR (or focus that worktree’s card in Canvas):

• Open Pull Request on GitHub — open it in the browser. (⌘⌃G “Open on Code Host” also opens the PR/repo page, including from Canvas.)
• Mark PR Ready for Review — convert a draft to ready (only when it’s a draft).
• Copy failing job URL — copy the first failing check’s URL.
• Copy CI Failure Logs — extract and copy the failed run’s logs (great to hand back to an agent to fix).
• Re-run Failed Jobs — re-trigger the latest failed workflow.
• Open Failing Check Details — open a failing check in the browser.
• Merge PR — merge when mergeable (not draft, checks pass, no conflicts, no changes requested). Merge strategy comes from pullRequestMergeStrategy (global) or the per-repo override (merge / squash / rebase).
• Close PR — close an open PR.

Requirements & settings#

• The gh CLI must be installed and authenticated (gh auth login). Prowl locates gh via which (directly, then through a login shell), falling back to common install paths (/opt/homebrew/bin, /usr/local/bin, ~/.local/bin) when the shell PATH misses it. Login-shell probing works even with a non-POSIX login shell (nushell, pwsh, …) — Prowl falls back to /bin/zsh for one-shot commands in that case.
• githubIntegrationEnabled (global) gates all GitHub features.
• Per repo: fetchPullRequestState (auto-fetch PR state; on by default — turn off for big/expensive repos), pullRequestMergeStrategy override, and githubAccountOverride for repositories that need a specific gh account.
• Settings → GitHub tab shows every authenticated gh host/account and which account is active for each host.

When a repository has githubAccountOverride set, Prowl temporarily runs gh auth switch --hostname <host> --user <login> before GitHub operations for that repository, then switches the host back to the previously active account. This uses gh’s stored authentication state; Prowl still never reads or stores GitHub tokens.

Gotchas for agents#

• No gh / not authenticated → no PR features. If a human expects PR actions and they’re missing, check gh auth status.
• If a repo is pinned to a specific GitHub identity and PR actions fail, verify that gh auth status lists that account on the repo’s host.
• PR actions appear in the palette only when the selected worktree’s branch has a PR. No PR → no actions.
• “Copy CI Failure Logs” is the high-value loop for agents: copy logs → feed to the agent → it fixes → “Re-run Failed Jobs”.