Skip to content

About

A TUI tool to manage the merge queue for brioche-packages

Resources

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

58 Commits

Folders and files

Repository files navigation

brioche-merge-manager

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 / a and 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

Screenshot

Brioche Merge Manager showing the PR list on the left with a selected PR's diff panel open on the right, and the bulk selection legend at the bottom


Requirements


Token Permissions

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.


Installation

git clone https://github.com/brioche-dev/brioche-merge-manager
cd brioche-merge-manager
cargo build --release

The compiled binary will be at target/release/brioche-merge-manager.


Configuration

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)

Example .env

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
GITHUB_OWNER=brioche-dev
GITHUB_REPO=brioche-packages

Usage

cargo run
# or after building:
./target/release/brioche-merge-manager

# start with the diff panel open
./target/release/brioche-merge-manager --diff
cargo run -- --diff

Flags

Flag Description
--diff Open the diff panel on startup (equivalent to pressing Enter after the first PR loads)

Keybindings

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.

Filters

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.


How It Works

On launch (and on R) the app fetches all open PRs using a two-phase parallel GraphQL strategy:

  1. Phase 1 — cursor collection (sequential, lightweight): pages through pullRequests fetching only pageInfo and totalCount to collect all page-start cursors cheaply.
  2. 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.


Tracing Logs

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.

Enable logging

DEBUG_LOG=/tmp/bmm.log cargo run

Watch the log in a second terminal:

tail -f /tmp/bmm.log

Control verbosity with RUST_LOG

RUST_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

Log levels used

Level What is logged
DEBUG Startup, phase transitions, page counts, enqueue/retry calls
TRACE Per-PR parse details, full GraphQL response bodies (verbose)

Example output

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

Dependencies

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

About

A TUI tool to manage the merge queue for brioche-packages

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages