gitlab-roulette-cli

GitLab Roulette CLI

A Terminal User Interface (TUI) application for tracking GitLab maintainers' review workload and availability.

Overview

GitLab Roulette CLI provides a command-line dashboard that replicates the functionality of the GitLab Roulette web application, allowing you to view reviewer availability, workload statistics, and pick random available reviewers directly from your terminal.

Demo

Overview & Navigation

Browse people, filter by name, and view detailed profiles:

Project Selection

Switch between GitLab projects with filtering:

Role Selection

Multi-select roles with live filtering:

Features

• View reviewer availability and capacity
• Filter by project and role
• Sort by various metrics (name, assignments, local time, timezone)
• Availability filtering modes
• Work hours filter
• Roulette feature - pick random available reviewers
• View historical capacity data
• Display assignment statistics and trends

Technology Stack

• Language: Go
• Framework: Bubbletea (Elm Architecture)
• UI Libraries: Lipgloss (styling), Bubbles (components)

Data Source

This application fetches data from publicly available static JSON files generated by the GitLab Roulette pipeline. No authentication is required.

Caching

To improve performance, fetched data is cached locally for 10 minutes. The cache is shared between CLI commands and TUI, providing a seamless experience:

• First run (CLI or TUI): Fetches from API (~2 seconds)
• Subsequent runs: Uses cache (instant, ~50ms)
• Cache expires after 10 minutes, then auto-refreshes
• Cross-usage: Run a CLI command, then launch TUI instantly with cached data

Performance improvement: 20-40x faster with cache

Cache location: ~/.cache/gitlab-roulette-cli/stats.json (macOS/Linux)

Cache commands:

# Show cache status
gitlab-roulette-cli cache info

# Clear cache manually
gitlab-roulette-cli cache clear

Installation

From Source

Prerequisites: Go 1.25.6 or later

Clone and build:

git clone https://gitlab.com/ck3g/gitlab-roulette-cli.git
cd gitlab-roulette-cli
go build -o bin/gitlab-roulette
./bin/gitlab-roulette

Or install directly:

go install gitlab.com/ck3g/gitlab-roulette-cli@latest

Homebrew

Coming soon.

Documentation

📚 Command Reference: Detailed auto-generated documentation for all commands is available in docs/commands/.

This README contains quick start examples and common use cases. For comprehensive command documentation including all flags and options, see the command reference.

Usage

Quick Start

Launch the TUI application:

gitlab-roulette-cli

Open the web dashboard in your browser:

gitlab-roulette-cli web

CLI Commands (Non-Interactive)

List Available Roles

Discover which roles are available for a project:

# List roles for default project (gitlab)
gitlab-roulette-cli roles

# List roles for a specific project
gitlab-roulette-cli roles --project gitaly

# Output as JSON
gitlab-roulette-cli roles --json

Example output:

Project: gitlab

Available roles (37):
  maintainer::authentication
  maintainer::backend
  maintainer::frontend
  reviewer::backend
  reviewer::frontend
  ...

List People

List all people matching the specified criteria (not random, full list):

# List all people in default project
gitlab-roulette-cli list

# List all backend reviewers/maintainers
gitlab-roulette-cli list --role backend

# List multiple roles (matches ANY role)
gitlab-roulette-cli list --role backend --role frontend

# Specify a different project
gitlab-roulette-cli list --role maintainer --project gitaly

# Only show available people (not on PTO/vacation)
gitlab-roulette-cli list --role backend --available

# Only show people in work hours (9am-5pm local time)
gitlab-roulette-cli list --role backend --work-hours

# Limit number of results (like git log -n)
gitlab-roulette-cli list --role backend -n 10
gitlab-roulette-cli list --available --limit 5

# Combine filters
gitlab-roulette-cli list --role backend --available --work-hours -n 20

# Output as JSON for scripting
gitlab-roulette-cli list --role backend --json

Example output:

Project: gitlab
Matched roles: maintainer::backend, reviewer::backend

People (5):
  @johndoe (John Doe) - 3 MR reviews pending
  @janedoe (Jane Doe) - No MR reviews pending
  @alice (Alice Smith) - 1 MR review pending
  @bob (Bob Johnson) - 5 MR reviews pending
  @charlie (Charlie Brown) - 2 MR reviews pending

Flags:

• --role (optional) - Role substring to match (e.g., "backend", "maintainer::backend"). Use gitlab-roulette-cli roles to see available roles. If not specified, lists all people.
• --project (optional) - Project name (default: "gitlab")
• --available (optional) - Only show available people (not on PTO/vacation)
• --work-hours (optional) - Only show people in 9am-5pm local time
• -n, --limit (optional) - Limit number of results (default: unlimited)
• --json (optional) - Output as JSON instead of human-readable

Use cases:

• See the full pool of available reviewers before deciding
• Get a complete list for scripting or automation
• Check workload distribution (MR review counts)
• Quick check of who's available right now: list --available -n 10
• Pipe to other tools: list | less for long lists

Check Availability

Check if a specific person is available, or count available people matching criteria:

# Check if a specific person is available
gitlab-roulette-cli available @johndoe
gitlab-roulette-cli available johndoe

# Count available people for a role
gitlab-roulette-cli available --role backend --count

# List available people for a role
gitlab-roulette-cli available --role backend

# Count all available people in project
gitlab-roulette-cli available --count

# Only count people in work hours
gitlab-roulette-cli available --role backend --work-hours --count

# JSON output
gitlab-roulette-cli available @johndoe --json

Example output (checking specific person):

✓ @alexbuijs is available

Name: Alex Buijs
MR reviews pending: 5

Example output (counting):

154 available people matching roles: maintainer::backend

Flags:

• username (positional, optional) - Check specific person's availability
• --role (optional) - Role substring to match. Use with --count to count available people.
• --project (optional) - Project name (default: "gitlab")
• --count (optional) - Show count instead of list
• --work-hours (optional) - Only check people in 9am-5pm local time
• --json (optional) - Output as JSON instead of human-readable

Use cases:

• Quick check before assigning a review: available @username
• See how many reviewers are available: available --role backend --count
• Find available reviewers during work hours: available --role frontend --work-hours
• Scripting and automation with JSON output

Workload Statistics

Show workload statistics to make informed decisions about reviewer assignments:

# Show stats for a specific person
gitlab-roulette-cli stats @johndoe

# Show stats for a role
gitlab-roulette-cli stats --role backend

# Show stats for multiple roles (combined)
gitlab-roulette-cli stats --role backend --role frontend

# Only show available people
gitlab-roulette-cli stats --role backend --available

# Only show people in work hours
gitlab-roulette-cli stats --role backend --work-hours

# JSON output
gitlab-roulette-cli stats --role backend --json

Example output (person):

Stats for @alexbuijs (Alex Buijs)

Status: ✓ Available
MR reviews pending: 0

Activity (last 30 days):
   7 days:  26 events  ( 3.7/day)
  30 days: 110 events  ( 3.7/day)

Roles:
  • maintainer::backend (gitlab)

Departments:
  • Sec Engineering
  • Development Department

Local time: UTC+01:00

Example output (role):

Stats for role: maintainer::backend
Project: gitlab

Overview:
  Total people: 263
  Available: 155 (59%)
  Total MR reviews pending: 669

Workload Distribution:
  Average MRs per person: 2.5
  Median: 2
  Min: 0
  Max: 15

Top 5 busiest reviewers:
  1. @user1 - 15 MR reviews (24 events/week)
  2. @user2 - 13 MR reviews (5 events/week)
  ...

Top 5 available with low workload:
  1. @user3 - 0 MR reviews (0 events/week)
  2. @user4 - 0 MR reviews (1 events/week)
  ...

Flags:

• username (positional, optional) - Show stats for specific person
• --role (optional) - Role substring to match
• --project (optional) - Project name (default: "gitlab")
• --available (optional) - Only include available people
• --work-hours (optional) - Only include people in 9am-5pm local time
• --json (optional) - Output as JSON instead of human-readable

Use cases:

• Check individual workload before assigning: stats @username
• See workload distribution across a role: stats --role backend
• Find available reviewers with light workload for assignment
• Identify who's overloaded (busiest reviewers list)
• Data-driven review assignments

Search People

Find people by name, username, or department - quick lookup without opening the TUI:

# Search by name or username
gitlab-roulette-cli search "alex"

# Search by department
gitlab-roulette-cli search --department "backend"

# Combine name and department
gitlab-roulette-cli search "alex" --department "engineering"

# Search with role filter
gitlab-roulette-cli search "alex" --role backend

# Only show available people
gitlab-roulette-cli search "alex" --available

# Limit results
gitlab-roulette-cli search "alex" -n 5

# JSON output
gitlab-roulette-cli search "alex" --json

Example output:

Search results (query: "alex")

3 people found:

@alexbuijs (Alex Buijs)
  Status: ✓ Available
  Roles: maintainer::backend (gitlab)
  Departments: Sec Engineering, Development Department
  MR reviews: 5 pending

@alexandra (Alexandra Smith)
  Status: ✓ Available
  Roles: reviewer::frontend (gitlab)
  Departments: Frontend Team
  MR reviews: 2 pending

Flags:

• query (positional, optional) - Search query for name/username
• --department (optional) - Filter by department substring
• --role (optional) - Filter by role substring
• --project (optional) - Project name (default: "gitlab")
• --available (optional) - Only show available people
• -n, --limit (optional) - Limit number of results
• --json (optional) - Output as JSON

Use cases:

• Quick lookup without opening TUI: search "alex"
• Find team members by department: search --department "backend"
• Check who's available: search "alex" --available
• Scripting and automation with JSON output

Spin the Wheel

Pick a random available person from the command line:

# Pick a backend reviewer/maintainer
gitlab-roulette-cli spin --role backend

# Pick from multiple roles (matches ANY role)
gitlab-roulette-cli spin --role backend --role frontend

# Specify a different project
gitlab-roulette-cli spin --role maintainer --project gitaly

# Only pick people in work hours (9am-5pm local time)
gitlab-roulette-cli spin --role backend --work-hours

# Output as JSON for scripting
gitlab-roulette-cli spin --role backend --json

Example output:

Project: gitlab
Matched roles: maintainer::backend, reviewer::backend
Selected: @johndoe (John Doe)

Flags:

• --role (required) - Role substring to match (e.g., "backend", "maintainer::backend"). Use gitlab-roulette-cli roles to see available roles.
• --project (optional) - Project name (default: "gitlab")
• --work-hours (optional) - Only pick people in 9am-5pm local time
• --json (optional) - Output as JSON instead of human-readable

Note: The spin command always filters to available people only (never picks people on PTO/vacation).

Basic Navigation

The application displays GitLab maintainers and reviewers with their availability, workload, and timezone information. Use keyboard shortcuts to filter, sort, and interact with the data.

Main Screen Layout:

• Header: Project selection and active roles
• Role Labels: Color-coded labels showing selected roles
• People Grid: Cards showing reviewers with their info
• Help Bar: Quick reference of available shortcuts

Keyboard Shortcuts

Essential Actions

Key	Action
?	Show help modal with searchable shortcuts
q	Quit application
Ctrl+R	Refresh/reload data from server

Navigation

Key	Action
Tab	Select next person card
Shift+Tab	Select previous person card
↑↓ or j/k	Scroll through people list
Enter	Open person details modal
Esc	Close modal or clear filter

Filtering

Key	Action
/	Filter people by name or username
p	Select project
r	Select roles (multi-select)
u	Toggle unavailable folks (show/fade/hide)
h	Toggle work hours filter (all/9-5 local time)
o	Order/sort people by various criteria

Actions

Key	Action
s	Spin the wheel - pick random available person
Ctrl+C	Copy username to clipboard (when card selected)

Features Guide

Project Selection (p)

• Browse all available GitLab projects
• Press / to filter projects by name
• Navigate with ↑↓ or j/k
• Press Enter to select, Esc to cancel

Role Selection (r)

• Multi-select roles (reviewer, maintainer, by specialty)
• Press Space to toggle role selection
• Press a to select all, n to deselect all
• Press / to filter roles by name
• Press Enter to apply, Esc to cancel

Sorting Options (o)

Choose from 12 sort options:

• Name (A→Z or Z→A)
• Review Count (ascending or descending)
• Assign Events - 7 days (ascending or descending)
• Assign Events - 30 days (ascending or descending)
• Local Time (ascending or descending)
• Timezone (ascending or descending)

Availability Modes (u)

Cycle through three modes:

• Show All - Display everyone
• Fade Unavailable - Dim unavailable people
• Hide Unavailable - Filter out unavailable people

Work Hours Filter (h)

Toggle between:

• All - Show people regardless of their local time
• 9-5 - Only show people within 9am-5pm local time

Spin the Wheel (s)

Pick a random person from the currently filtered list. Great for:

• Finding available reviewers
• Load balancing review assignments
• Quick random selection

Person Detail View

When you select a card and press Enter, you'll see:

• Full name and username
• All roles with project assignments
• Departments
• Status emoji and message
• Local time with timezone offset
• Activity sparklines (7-day and 30-day trends)
• List of pending MR reviews (clickable links)

Press Ctrl+C to copy username, Enter/Esc/q to close.

Tips

• Use the help modal (?) - It's searchable! Type to filter shortcuts by keyword
• Combine filters - Use project + roles + availability + work hours together for precise filtering
• Name filter (/) works independently of other filters for quick searches
• Empty states provide helpful hints when no results are found
• Refresh (Ctrl+R) updates data without restarting the app

Development

This project uses mise for managing Go versions and task automation.

Running from Source

With mise:

mise run run

Or with standard Go commands:

go run main.go

Available Tasks

mise run test          # Run tests
mise run test:cover    # Run tests with coverage
mise run build         # Build binary
mise run lint          # Run all linters
mise run lint:fix      # Run linters with auto-fix
mise run fmt           # Check code formatting
mise run fmt:fix       # Fix code formatting

See .mise.toml for the complete list of available tasks.

License

MIT License - see LICENSE file for details.