A terminal UI for managing GitHub merge queues on the brioche-dev/brioche-packages repository.
Shows all open PRs, highlights which are ready to queue or removed from the merge queue, lets you queue or retry them in GitHub's native merge queue, and opens any PR in your browser — all without leaving the terminal.
- Bulk enqueue — select multiple PRs with
Space/aand add them all to the merge queue in a single batched GraphQL request - Mouse support — click filter tabs and the diff panel to navigate without the keyboard; scroll wheel navigates the PR list or scrolls the diff depending on cursor position
- Rust 1.75+
- A GitHub personal access token (see Token Permissions below)
The GITHUB_TOKEN must be a fine-grained personal access token with the
following repository permissions for the target repo:
| Permission | Access |
|---|---|
| Merge queues | Read and write |
| Pull requests | Read and write |
| Metadata | Read |
| Contents | Read and write |
| Actions | Read |
Create one at GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens.
git clone https://github.com/brioche-dev/brioche-merge-manager
cd brioche-merge-manager
cargo build --releaseThe compiled binary will be at target/release/brioche-merge-manager.
Configuration is via environment variables. Copy .env.example to .env for
local development, or export them in your shell.
| Variable | Required | Default | Description |
|---|---|---|---|
GITHUB_TOKEN |
Yes | — | GitHub fine-grained personal access token (see Token Permissions) |
GITHUB_OWNER |
No | brioche-dev |
Repository owner |
GITHUB_REPO |
No | brioche-packages |
Repository name |
BROWSER |
No | system default | Browser command to use when pressing o |
DEBUG_LOG |
No | — | Path to write trace logs to (see Tracing Logs) |
RUST_LOG |
No | debug |
Log filter when DEBUG_LOG is set (see Tracing Logs) |
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_OWNER=brioche-dev
GITHUB_REPO=brioche-packagescargo run
# or after building:
./target/release/brioche-merge-manager
# start with the diff panel open
./target/release/brioche-merge-manager --diff
cargo run -- --diff| Flag | Description |
|---|---|
--diff |
Open the diff panel on startup (equivalent to pressing Enter after the first PR loads) |
PR list navigation
| Key | Action |
|---|---|
↑ / k |
Move selection up |
↓ / j |
Move selection down |
Page Up |
Jump up one page |
Page Down |
Jump down one page |
Home |
Jump to first PR |
End |
Jump to last PR |
Tab |
Cycle filter forward |
Shift+Tab |
Cycle filter backward |
Bulk selection
| Key | Action |
|---|---|
Space |
Toggle the current PR in/out of the selection |
a |
Select all PRs visible under the current filter |
A |
Deselect all |
r |
Add selected PRs to the merge queue (single batched request); if nothing is selected, enqueues the current PR |
Selected PRs show a ✓ marker in the list. The spinner in the status bar reads Adding N PRs to merge queue… while the request is in flight.
Actions
| Key | Action |
|---|---|
r |
Add to merge queue (see Bulk selection above) |
o |
Open selected PR in browser |
Enter |
Toggle diff panel |
d |
Focus/unfocus diff panel for scrolling (when open) |
R |
Refresh PR list |
Ctrl+C |
Quit |
Mouse
| Action | Effect |
|---|---|
| Click a filter tab | Switch to that filter |
| Click the diff panel | Focus the diff panel for keyboard scrolling |
| Click the diff panel again | Unfocus (restore PR list navigation) |
| Scroll wheel over the diff panel | Scroll the diff (3 lines per notch) |
| Scroll wheel elsewhere | Move PR list selection up/down |
Diff panel (Enter to open; d to focus for scrolling; or pass --diff to open on startup)
| Key | Action |
|---|---|
↑ / k |
Scroll diff up |
↓ / j |
Scroll diff down |
Page Up |
Scroll diff up one page |
Page Down |
Scroll diff down one page |
Home |
Jump to top of diff |
End |
Jump to bottom of diff |
d |
Unfocus diff (restore PR list navigation) |
Enter |
Close diff panel |
project.bri files are always sorted to the top of the diff view.
The tab bar at the top of the PR list cycles through four views:
| Filter | Shows |
|---|---|
| Active | All open PRs (default) |
| Ready | Non-draft PRs with a clean merge state, not yet queued |
| Removed | PRs removed from the merge queue and not currently re-queued |
| Queued | PRs currently in the merge queue, sorted by position (longest-waiting first) |
When a PR is shown as Removed due to failed status checks, the detail panel displays the latest workflow run URL for quick access to the CI logs.
On launch (and on R) the app fetches all open PRs using a two-phase parallel
GraphQL strategy:
- Phase 1 — cursor collection (sequential, lightweight): pages through
pullRequestsfetching onlypageInfoandtotalCountto collect all page-start cursors cheaply. - Phase 2 — parallel fetch: fires all full-data page requests
simultaneously using
tokio::task::JoinSet, then reassembles them in order.
Each PR's status is derived from mergeStateStatus, mergeQueueEntry, and
timelineItems (merge queue removal events):
| Status | Condition |
|---|---|
| Ready to merge | mergeStateStatus = CLEAN and not currently in the merge queue |
| In queue | Has an active mergeQueueEntry (any state) |
| Removed | Has a REMOVED_FROM_MERGE_QUEUE_EVENT in its timeline and is not currently re-queued |
Draft PRs display their real merge state with a draft badge and are excluded
from the Ready filter since they cannot be queued.
Because the TUI owns the terminal at runtime, logs cannot be written to
stdout or stderr. Instead, set DEBUG_LOG to a file path and the app will
append structured traces there using the tracing
ecosystem.
DEBUG_LOG=/tmp/bmm.log cargo runWatch the log in a second terminal:
tail -f /tmp/bmm.logRUST_LOG accepts the standard tracing-subscriber filter syntax. When
DEBUG_LOG is set but RUST_LOG is not, the default level is debug.
# debug level (default)
DEBUG_LOG=/tmp/bmm.log cargo run
# trace level — includes per-PR parse details and full GraphQL response bodies
RUST_LOG=trace DEBUG_LOG=/tmp/bmm.log cargo run
# only this crate's logs at debug, suppress noisy dependencies
RUST_LOG=brioche_merge_manager=debug DEBUG_LOG=/tmp/bmm.log cargo run
# this crate at trace, everything else at warn
RUST_LOG=brioche_merge_manager=trace,warn DEBUG_LOG=/tmp/bmm.log cargo run| Level | What is logged |
|---|---|
DEBUG |
Startup, phase transitions, page counts, enqueue/retry calls |
TRACE |
Per-PR parse details, full GraphQL response bodies (verbose) |
2025-03-19T14:22:01.483Z DEBUG brioche_merge_manager: starting owner=brioche-dev repo=brioche-packages
2025-03-19T14:22:01.612Z DEBUG brioche_merge_manager::github::graphql: collect_page_cursors: done pages=6 total_count=287
2025-03-19T14:22:01.613Z DEBUG brioche_merge_manager::github::graphql: fetch_all_prs_bulk: fetching pages in parallel pages=6 total_count=287
2025-03-19T14:22:02.104Z DEBUG brioche_merge_manager::github::graphql: fetch_pr_page: received nodes page=2 count=50
2025-03-19T14:22:02.201Z DEBUG brioche_merge_manager::github::graphql: fetch_pr_page: received nodes page=0 count=50
2025-03-19T14:22:02.309Z DEBUG brioche_merge_manager::github::client: fetch_managed_prs: done count=287
| Crate | Purpose |
|---|---|
ratatui |
Terminal UI framework |
crossterm |
Cross-platform terminal backend |
tokio |
Async runtime |
reqwest |
HTTP client for GitHub GraphQL API |
octocrab |
GitHub API client (authentication) |
serde / serde_json |
JSON serialisation |
tracing / tracing-subscriber |
Structured logging |
webbrowser |
Cross-platform browser opening (WSL2-aware) |
anyhow |
Error handling |
dotenvy |
.env file loading |
