🚀 GitLab MR Tracker

GitLab MR Tracker is a fast, asynchronous Terminal User Interface (TUI) dashboard designed for engineering teams. It provides real-time verification of GitLab Merge Requests across target environment branches (main, preproduction, staging, etc.), handling strict SHA verification as well as cherry-picked commit identification.

✨ Key Features

• 🔐 OS Keyring Integration (Zero Plain-Text Secrets): Personal Access Tokens (PAT) can be securely stored directly in your OS secret manager (GNOME Keyring, KWallet, macOS Keychain, or Windows Credential Manager).

• 🏷️ Dynamic Scoped Labels & Custom Chips:

  • Smart Filtering: Configure specific label prefixes (e.g., deploy::, review::) to display cleanly as colored chips in the main table grid, while keeping all attached tags visible in the side inspector panel.
  • Customizable Palette: Map label names or wildcard patterns (e.g., deploy::*) to custom terminal colors or standard HEX codes (#FF5733) via an XDG-compliant JSON config.

• ⚡ High Performance & Asynchronous: Powered by tokio and reqwest, utilizing non-blocking event loops and bounded concurrent requests via semaphores to protect GitLab API rate limits.

• 🛡️ Pass-Through Pass Caching: Core MR metadata (author, milestone, assignee, description, labels) is fetched once and cached locally. Fully deployed MRs bypass network re-queries entirely ("Green Pass").

• 🔍 Dual Match Verification Engine:

  • System 1 (Strict SHA): Validates precise merge/squash commit SHAs on target branches (resistant to git reset --hard).
  • System 2 (Intelligent Fuzzy Matcher): Uses a keyword relevance matrix to verify cherry-picked commits deployed across branches.

• 🖥️ Responsive Flexbox TUI Grid: Features a dynamic layout engine (Constraint::Fill) that seamlessly scales table columns and side panels from 1080p laptop displays to ultra-wide 4K monitors without empty trailing spaces.

• 🔃 Smart Auto-Sorting by Last Update: The dashboard defaults to sorting MRs by updated_at (most recently pushed to remote first), automatically re-applied after each refresh. Cycle through sort columns (S) and toggle direction (Shift+S). The active sort is always visible in the table title bar.

• 🌐 Browser Integration: Open any selected MR directly in your default browser with a single keypress (O).

• 🔔 Smart Desktop Notifications: Receives native OS desktop notifications only when an MR's branch status has changed since the last run — no duplicate alerts on restart or redundant refreshes.

• 📁 XDG-Compliant Persistence: Saves tracked dashboard state, UI configurations, and last-known branch statuses automatically to platform-standard configuration paths using directories.

• Customizable Refresh Interval: Tailor the background polling rate to your needs (defaults to 15 minutes / 900s) via config.json or the GITLAB_REFRESH_INTERVAL_SECS environment variable.

• 📊 Activity Badge: Each MR in the Context Inspector displays a color-coded activity badge based on its updated_at timestamp — 🟢 Active, 🟡 Slowing, or 🔴 Stale. Thresholds are fully configurable via config.json or environment variables (ACTIVITY_RECENT_DAYS, ACTIVITY_STALE_DAYS).

• 🔀 Animated Mergeability Badge: For open MRs, the Status column alternates every second between the base Open badge and a live mergeability indicator sourced directly from the GitLab API:

  Badge	Color	Meaning
  Mergeable	🟩 Light green	MR can be merged cleanly
  Conflict	🟥 Red	Merge conflicts must be resolved
  Rebase	🟨 Yellow	Branch is behind target — rebase required

  No extra column is added: the animation keeps the layout compact while surfacing critical merge-readiness at a glance.

• 🔬 Pipeline Inspector (P): Press P on any selected MR to toggle the side panel between MR metadata and its pipeline history. The last 5 pipeline runs are displayed with per-stage job breakdown, status icons, and execution durations:

  #9981  ✔ passed
    ▸ test
      ✔ lint        (18s)
      ✔ unit-tests  (74s)
    ▸ build
      ✔ build       (42s)
    ▸ deploy
      ✔ deploy-staging (31s)
  

  Pipeline data is fetched alongside MR metadata in the same refresh cycle and persisted to disk — so it is immediately available on restart without an extra network call. Re-fetching only occurs when GitLab reports a new updated_at timestamp, keeping API usage minimal.

🔑 Authentication & Configuration

The application requires your GitLab Project configuration and an API Personal Access Token.

Step 1: Set up environment variables

1. Copy the provided template to create your local .env file:

   cp .env.example .env
   

2. Open .env and specify your project details:

   # Required: Your target GitLab Project ID
   GITLAB_PROJECT_ID=12345678
   
   # Optional: Custom self-hosted GitLab instance (Defaults to https://gitlab.com if omitted)
   GITLAB_URL=https://gitlab.my-company.com
   
   # Optional: Override token via environment variable (Not recommended for disk storage)
   # GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
   
   # Optional: Override initial tracked branches for new sessions (comma-separated)
   DEFAULT_BRANCHES="main,develop"
   
   # Optional: Filter table column tags by prefix (comma-separated)
   TABLE_LABEL_PREFIXES="deploy::,review::"
   
   # Optional: Activity badge thresholds in the Context Inspector (in days)
   ACTIVITY_RECENT_DAYS=2   # 🟢 Green if updated within N days (default: 2)
   ACTIVITY_STALE_DAYS=7    # 🔴 Red if not updated for N days (default: 7)
   

🔄 Settings Resolution Order

Settings are resolved in the following order (highest to lowest priority):

1. System Environment Variables & Local .env (current directory)
2. Global .env (~/.config/gitlab-tracker/.env)
3. User Config File (~/.config/gitlab-tracker/config.json)
4. Built-in Fallback Defaults (https://gitlab.com, ["main"] for default branch)

Step 2: Keyring PAT Security Layer

Your GitLab personal access token is never stored in plain text.

Upon first launch, if no token is found, gitlab-tracker will securely prompt you for your token and store it in your operating system's native secure keyring (GNOME Keyring, macOS Keychain, or Windows Credential Manager).

 ┌────────────────────────────────────────────────────────┐
 │                   TOKEN LOOKUP ORDER                   │
 ├────────────────────────────────────────────────────────┤
 │ 1. GITLAB_TOKEN environment variable (if set)          │
 │ 2. Native OS Keyring (GNOME Keyring / macOS Keychain)  │
 │ 3. Interactive CLI Prompt (First run fallback)         │
 └────────────────────────────────────────────────────────┘

1. First-Run Onboarding: If no GITLAB_TOKEN is found in your .env or environment, the application will prompt you interactively in the terminal on its initial launch:

   🔑 No GITLAB_TOKEN found in environment or system Keyring.
   Please enter your GitLab Personal Access Token: glpat-xxxxxxxxxxxx
   ✅ Token securely saved to OS Keyring!
   

2. Secure Token Persistence: The token is encrypted and handed off directly to your operating system's native secret manager:

   • Linux: GNOME Keyring / KWallet via Secret Service API
   • macOS: Apple Keychain Service
   • Windows: Windows Credential Manager

3. Subsequent Launches: You can delete the GITLAB_TOKEN entry from your .env completely. On subsequent runs, gitlab-tracker retrieves the token silently from the OS Keyring without requiring plain-text files or manual re-entry.

Step 3: UI, Default Branches & Label Customization (config.json)

On its first launch, the tool automatically generates a config.json file inside your OS user configuration directory:

• Linux: ~/.config/gitlab-tracker/config.json
• macOS: ~/Library/Application Support/gitlab-tracker/config.json
• Windows: C:\Users\<User>\AppData\Roaming\gitlab-tracker\config.json

You can edit this file to adjust default environment branches, label badge colors, wildcard rules, and activity badge thresholds:

{
  "project_id": "12345678",
  "gitlab_url": "https://gitlab.my-company.com",
  "refresh_interval_secs": 900,
  "default_branches": [
    "main"
  ],
  "table_label_prefixes": [
    "deploy::",
    "review::"
  ],
  "activity_recent_days": 2,
  "activity_stale_days": 7,
  "label_colors": {
    "deploy::*": {
      "bg": "#2E7D32",
      "fg": "white"
    },
    "review::approved": {
      "bg": "magenta",
      "fg": "white"
    },
    "review::*": {
      "bg": "cyan",
      "fg": "black"
    },
    "size::*": {
      "bg": "dark_gray",
      "fg": "white"
    },
    "bug": {
      "bg": "#D32F2F",
      "fg": "white"
    }
  }
}

Activity badge thresholds control the colored indicator displayed next to the Updated field in the Context Inspector:

Badge	Meaning	Condition
🟢 Active	Updated recently	elapsed days < activity_recent_days
🟡 Slowing	Activity slowing down	between the two thresholds
🔴 Stale	No recent activity	elapsed days ≥ activity_stale_days
⬛ Unknown	Timestamp unavailable	—

🔔 How Desktop Notifications Work:

Notifications are powered by notify-rust and rely on your system's native notification daemon (e.g., libnotify on Linux, NSUserNotifications on macOS).

A notification is sent only when a branch is newly detected for a given MR — i.e., when the branch was not present in the last persisted state (tracker_state.json). This means:

• ✅ No duplicate alerts when restarting the app with an unchanged state.
• ✅ No spam during periodic background refreshes if nothing changed.
• ✅ Reliable detection of new deployments across refreshes and restarts.

The last-known branch state per MR is persisted in tracker_state.json under the last_known_branches key. On the very first launch (empty state), a single batch of notifications may be sent for all already-known branches — this is a one-time occurrence.

🌿 How Branch Resolution Works:

1. Active Session Priority: If tracker_state.json exists from a previous run, the app restores your last active layout (columns added/removed via input).
2. First Run / Fresh Session: If no state exists, initial branches are loaded from DEFAULT_BRANCHES in .env if provided, falling back to default_branches in config.json (defaults to ["main"]).

📦 Installation

Recommended — Install from crates.io

The simplest way to install gitlab-tracker if you have Rust (1.80+) available:

cargo install gitlab-tracker

This downloads, compiles, and installs the latest published release directly from crates.io into ~/.cargo/bin/. No cloning required.

Pre-built Binaries

If you prefer not to compile, download the latest pre-compiled binary for your architecture from the Releases Page and place it somewhere on your $PATH.

Building from Source

For development or to test unreleased changes, clone the repository and build manually:

git clone git@github.com:julien-langlois/gitlab-tracker.git
cd gitlab-tracker

# Build optimized release executable
cargo build --release

# Optional: install binary globally to ~/.cargo/bin/
cargo install --path .

Once installed via any of the methods above, launch the dashboard from any terminal folder:

gitlab-tracker

⌨️ Dashboard Navigation & Shortcuts

The dashboard operates in two keyboard modes, inspired by vim:

🟦 Normal Mode (default)

Shortcut keys are active. The input field is passive.

🟨 Insert Mode

The input field has exclusive focus. All printable keys feed the field — shortcuts are suspended. The input bar turns yellow as a visual indicator.

Why two modes? Branch names starting with s, S, p, P, o, O, r or R would otherwise collide with shortcut keys. Insert mode guarantees the full branch name is captured without interference.

🏗️ Project Architecture

src/
├── main.rs          # Event loop orchestrator & async channel setup
├── app.rs           # State machine, InputMode, row navigation & sort logic
├── config.rs        # Label filtering, wildcard matching, HEX color parsing & activity badge
├── models.rs        # Strongly-typed API DTOs & runtime event types
├── gitlab.rs        # Async network handling & rate-limit semaphores
├── events.rs        # Keyboard & mouse event dispatch (Normal / Insert mode routing)
├── storage.rs       # OS Keyring interface & XDG state/config persistence
├── utils.rs         # Fuzzy matching algorithmic utilities
├── demo.rs          # Demo mode with pre-populated mock data (screenshots & CI)
└── ui/
    ├── mod.rs       # Root layout renderer & input bar (mode-aware)
    ├── table.rs     # Main MR table widget
    └── inspector.rs # Side panel: MR metadata & pipeline history views

📄 License

Distributed under the MIT License. See LICENSE for details.