GitLab Runner TUI

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

Overview

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.

Preview

Seven dashboard tabs — navigate with 1–7 or Tab

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

Features

• 🚀 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

Quick Start

Prerequisites

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

Installation

From source:

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

Configuration

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

Running

# Using environment variables
gitlab-runner-tui

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

Dashboard Tabs

Tab	Description
Runners	Fetch all GitLab Runner details with optional filters
Health	Health check - verify all tagged runners are online
Offline	List runners with no online managers
Uncontacted	Find runners not contacted recently (default: 1 hour)
Empty	List runners with no managers
Rotating	Detect runners currently in rotation (multiple managers)
Workers	Show detailed list of all individual Runner Managers

Keyboard Navigation

• 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

Configuration Options

Environment Variables

Variable	Required	Default	Description
GITLAB_TOKEN	Yes	-	Personal access token accepted by GET /user
GITLAB_HOST	No	https://gitlab.com	GitLab instance URL

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

CLI Flags

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

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

• --watch: Enable headless mode; polls and logs to stdout instead of starting the TUI.
• --command <CMD>: Which query to run in watch mode (fetch, switch, flames, empty, rotate). Defaults to rotate.
• --tags <TAGS>: Comma-separated list of tags for filtering in watch mode.

Examples

Find all production runners

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

Check runner health

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

List offline runners

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

Watch for runner rotation (Headless)

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

Building

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run

Git Hooks

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

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

Troubleshooting

Connection Issues

Error: "Connection timeout"

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

Authentication Issues

Error: "Authentication failed"

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

Runner Target Issues

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

SSL Certificate Issues

Error: "SSL certificate verify failed"

• Self-signed certificate support is not currently implemented

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Architecture

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.

License

[Add your license here]

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

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