GitHub PR Status

The plugin finds the pull request for an environment's current branch by running gh in the environment's workspace on its machine, so forks, upstream remotes and the machine's own gh login apply. The sidebar row badge (the number in its state's color, shown when the threadRowMetadata experiment and Organize → Rows → Metadata are on), the composer banner, the Info panel and plugin-built sidebars read their PR status from it. Pending checks re-check about every 30 seconds in one batched GitHub request per machine.

bb pull-request show <environment-id> [--json]
bb pull-request ready <environment-id> [--json]
bb pull-request draft <environment-id> [--json]
bb pull-request merge <environment-id> [--method merge|squash|rebase] [--json]

• show prints the PR number, state, branch, attention, checks, review and mergeability. --json prints { "outcome": "available", "pullRequest" }, { "outcome": "absent" } or { "outcome": "unavailable", "message" }.
• ready needs a draft PR, draft needs an open PR and merge needs an open PR GitHub reports as mergeable. Each re-reads the PR first and fails with the reason otherwise.
• bb never wakes a machine for PR work. When the environment's machine is suspended or offline, show reports unavailable and the actions fail with a message naming the machine.
• gh must be installed and logged in on that machine.

The showPullRequest setting (default true) shows the pull request segment above the composer. Turn it off with bb plugin config bb--github-pr-status set showPullRequest false; the Info panel's Pull request row stays.

Other plugins read the same data through RPC. pullRequests is a keyed read: pass up to 200 environment ids and get one row per id. While a client watches a row, the plugin re-checks an open or draft PR every 30 seconds while any check is pending, auto-merge is on, the PR is queued or mergeability is unknown, and about every 5 minutes for other open or draft PRs. Merged and closed PRs do not poll. It also rechecks after a turn that ran gh, or discovers a PR after a turn on a branch without one. Environment status and branch changes refresh; ref changes read the local upstream OID and fetch only when it changes. App reads answer at once from what the plugin has and refresh a stale row in the background: open and draft PRs after 30 seconds, merged and closed PRs after an hour, a "no PR" result after 5 minutes. Opening a thread, including by loading the page on it, re-checks its PR on GitHub through refresh, whatever the row's age; other views ask again when they first show and each time the page shows again. CLI and RPC reads wait for a row older than 10 seconds. Call refresh with { environmentId } to re-check a row on GitHub now; it resolves once the row is current. Saved rows survive a restart. Environments sharing a PR share its fetch and timer, and viewers refresh only when the row changes.

experimental_useRpcKeyedQuery({
  pluginId: "bb--github-pr-status",
  contract,
  method: "pullRequests",
  keys: [environmentId],
});

bb plugin rpc inspect bb--github-pr-status prints the input and output schemas for pullRequests, markReady, markDraft and merge.