A fast, beautiful Terminal User Interface (TUI) for querying and inspecting GitLab Runners.

GitLab Runner TUI provides DevOps engineers and GitLab administrators with an intuitive command-line interface to monitor and manage GitLab Runner infrastructure. Query runners by tags—all from your terminal.

Seven dashboard tabs — navigate with 1–7 or Tab

Runner detail pane — arrow through runners to inspect status, version, managers, and tags

• 🚀 Interactive TUI - Beautiful, keyboard-driven interface built with ratatui
• 📊 Seven Dashboard Tabs - Specialized views for different runner and infrastructure metrics
• 🔍 Headless Watch Mode - Run in a non-interactive loop for CI/CD or monitoring
• 🏷️ Tag Filtering - Filter runners by comma-separated tags
• ⚡ Real-time API Queries - Direct integration with GitLab REST API v4
• 📊 Detailed Results - Tabular display of runners and managers with color highlighting
• 🔐 Secure - Token-based authentication

• GitLab personal access token accepted by the GitLab user API
• GitLab instance URL (defaults to gitlab.com)

From source:

git clone https://github.com/damacus/gitlab-runner-tui.git
cd gitlab-runner-tui
cargo build --release
./target/release/gitlab-runner-tui

Set required environment variables:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITLAB_HOST="https://gitlab.com"  # Optional, defaults to gitlab.com

Or create a .env file:

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_HOST=https://gitlab.com

Or create a config file at ~/.config/gitlab-runner-tui/config.toml:

gitlab_host = "https://gitlab.com"
gitlab_token = "glpat-xxxxxxxxxxxxxxxxxxxx"
poll_interval_secs = 30
poll_timeout_secs = 1800
discovery_mode = "configured_targets"

[[runner_targets]]
kind = "group"
id = "my-org/platform"
label = "Platform"

[[runner_targets]]
kind = "project"
id = "my-org/app"

If you launch the interactive TUI without a configured token, with a stale/invalid token, or without runner targets, the app now runs a setup flow and writes the canonical config file for you before entering the dashboard.

Runner discovery now comes from configured group/project targets instead of instance-wide runner listing. This is what makes normal GitLab.com usage possible.

Optional config.toml file locations (checked in this order):

1. ./config.toml (current working directory)
2. ~/.config/gitlab-runner-tui/config.toml (canonical)

Example:

poll_interval_secs = 30
poll_timeout_secs = 1800
gitlab_host = "https://gitlab.com"
gitlab_token = "glpat-xxxxxxxxxxxxxxxxxxxx"
discovery_mode = "configured_targets"

[[runner_targets]]
kind = "group"
id = "my-org/platform"
label = "Platform"

[[runner_targets]]
kind = "project"
id = "12345"
label = "App Project"

runner_targets are required when discovery_mode = "configured_targets". Set discovery_mode = "visible_runners" to use the current user's visible /runners endpoint instead. Supported target kinds:

• group
• project

Each target id may be either a numeric GitLab ID or a group/project path.

During onboarding, targets are entered as a single comma-separated prompt using explicit prefixes. In the interactive TUI you can also edit the discovery mode, token, targets, and poll settings from the settings modal.

group:my-org/platform,project:my-org/app

# Using environment variables
gitlab-runner-tui

# Or specify via CLI flags
gitlab-runner-tui --host https://gitlab.example.com --token glpat-xxx

• Tab / Shift+Tab - Switch dashboard tabs
• 1-7 - Jump directly to a tab
• ↑/↓ or k/j - Move table selection
• / or f - Focus tag filter input
• a - Edit the age filter
• v - Open version multi-select
• o - Cycle sort mode
• c - Open settings + diagnostics
• Enter or r - Refresh the active tab
• p - Toggle polling / auto-refresh
• Esc - Exit filter editing or dismiss errors
• ? - Toggle help
• q or Ctrl-C - Quit

runner_targets, discovery_mode, and polling settings can be edited in the TUI settings modal and are persisted back to the canonical config file.

In addition to the interactive TUI, gitlab-runner-tui can function as a powerful CLI tool for automation and LLM-based workflows.

Use the --once and --json flags to fetch data once and exit with a JSON response:

# Fetch all runners as JSON
gitlab-runner-tui --once --json --command fetch

# List only rotating runners as JSON
gitlab-runner-tui --once --json --command rotate

The JSON output includes both the runners data and metrics about the query. You can easily process this with jq:

List all runner IDs:

gitlab-runner-tui --once --json --command fetch | jq '.runners[].id'

Find runners with offline managers:

gitlab-runner-tui --once --json --command fetch | \
  jq '.runners[] | select(.managers[].status == "offline") | {id: .id, description: .description}'

Get query performance metrics:

gitlab-runner-tui --once --json --command fetch | jq '.metrics'

# Override host and token
gitlab-runner-tui --host <URL> --token <TOKEN>

# Headless mode (non-interactive)
gitlab-runner-tui --watch --command rotate --tags production
gitlab-runner-tui --once --json --command fetch

# Use demo data for any mode (no credentials required)
gitlab-runner-tui --demo
gitlab-runner-tui --demo --once --json

• --watch: Enable headless mode; polls and logs to stdout until timeout.
• --once: Run once and exit (ideal for scripts and automation).
• --json: Output results in JSON format (best combined with --once).
• --command <CMD>: Which query to run (fetch, switch, flames, empty, rotate). Defaults to rotate.
• --tags <TAGS>: Comma-separated list of tags for filtering.

1. Configure at least one group or project runner target
2. Select Runners tab (1)
3. Press / to enter tags: production
4. View filtered results

1. Configure at least one runner target
2. Select Health tab (2)
3. Press / to enter tags: production,linux
4. View health summary and runner statuses

1. Configure at least one runner target
2. Select Offline tab (3)
3. Press / to enter tags: alm
4. View runners with offline managers

Run in a non-interactive loop to monitor runners that have multiple managers (e.g. during a migration):

gitlab-runner-tui --watch --command rotate --tags prod

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run

This repo uses lefthook for local git hooks.

brew install lefthook
lefthook install

Configured hooks:

• pre-commit: cargo fmt --check and cargo clippy --all-targets -- -D warnings
• pre-push: cargo test

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

Error: "Connection timeout"

• Check GITLAB_HOST is correct and accessible
• Verify network connectivity: ping gitlab.com
• Check proxy settings if behind corporate firewall

Error: "Authentication failed"

• Verify GITLAB_TOKEN is correct
• Verify the token can authenticate against the GitLab user API
• Check token hasn't expired

Error: "At least one runner target must be configured"

• Add one or more [[runner_targets]] entries to config.toml
• Or rerun onboarding and enter targets like group:my-org/platform,project:my-org/app
• Or leave runner targets blank and use the current user's visible runners
• Confirm the configured group/project IDs or paths are valid for the current GitLab host

Error: "SSL certificate verify failed"

• Self-signed certificate support is not currently implemented

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

GitLab Runner TUI follows a three-layer architecture:

TUI (View) → Conductor (Business Logic) → GitLabClient (API)

• TUI Layer: User interface, event handling, rendering
• Conductor Layer: Orchestrates operations, applies filters, formats results
• GitLabClient Layer: HTTP communication with GitLab API

See app_spec.txt for detailed specification.

[Add your license here]

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ratatui - A Rust library for building terminal user interfaces.