GitLabSummaryCLI.osx-x64 0.2.4

gitlab-summary

A .NET 10 CLI tool and real-time dashboard for monitoring GitLab CI/CD pipeline activity across all projects in a group.

📚 Complete Documentation — Installation, guides, API reference, and more

Features

Core Functionality

• CLI Summary View — Compact table showing pipeline counts, pass/fail rates, and durations per project
• Detailed View — Per-pipeline breakdown with branch, source, commit, and timing info
• Real-time Dashboard — SSE-powered Vue 3 + Vuetify web dashboard with drill-down
• Cross-platform — Secure token storage via macOS Keychain, Windows DPAPI, or Linux DataProtection
• Flexible Filtering — Filter by project, configurable time range (minutes/hours/days)
• Subgroup Support — Includes nested subgroups by default

Dashboard Features

• Effective Pipeline Status — Shows true pipeline health based on actual job outcomes (green only when all jobs pass, orange for partial success)
• Enhanced Pipeline Charts — Hybrid chart with stacked success/partial areas and trend lines for failures
• Dynamic Group & Period Selection — Change GitLab group and time range without restarting server
• Group Hierarchy Browser — Tree-view modal to navigate and select groups (parent/siblings/children)
• AI-Powered Failure Analysis — Analyze failed jobs with Copilot, cache results, ask follow-up questions
• AI Analysis History — Dedicated page to view all cached AI analyses with pagination and search
• Enhanced Job Logs — GitLab CI section parsing with timing display, clean ANSI code handling
• Pipeline Details — View full pipeline details including jobs, commits, and notes from any context
• User Contributor Details — Click on any user to view their pipeline statistics and success rate
• Fork Detection — Visual badges indicate forked repositories
• Theme Persistence — Dark/light mode preference saved across sessions
• Responsive Navigation — Collapsible sidebar with saved state

Installation

Option 1: .NET Global Tool (Recommended)

dotnet tool install -g GitLabSummary

To update to the latest version:

dotnet tool update -g GitLabSummary

Option 2: Self-Contained Executables

Download pre-built executables from the Releases page:

• Windows: gitlab-summary-win-x64.exe
• macOS (Apple Silicon): gitlab-summary-osx-arm64
• macOS (Intel): gitlab-summary-osx-x64
• Linux: gitlab-summary-linux-x64

Option 3: Build from Source

# Clone the repository
git clone https://github.com/garrardkitchen/gitlab-summary.git
cd gitlab-summary

# Build the dashboard
cd src/dashboard
npm install
npm run build

# Build the CLI
cd ../cli
dotnet build

Prerequisites

• .NET 10 SDK (for building from source)
• GitLab Personal Access Token or Group Access Token with read_api scope
• GitHub Copilot subscription (for AI failure analysis):
  • GitHub account with active Copilot subscription
  • Authenticated with GitHub CLI: gh auth login
  • The Copilot SDK will automatically download the required CLI on first use

Quick Start

# Store your GitLab token securely
gitlab-summary token set --url https://gitlab.example.com

# View pipeline summary (last 24 hours)
gitlab-summary pipelines --group my-org

# View detailed breakdown
gitlab-summary pipelines --group my-org --since 2d --detailed

# Filter to a specific project
gitlab-summary pipelines --group my-org --project api-service --since 12h

# Start the real-time dashboard (opens browser automatically)
gitlab-summary serve --group my-org --open

Dashboard

# Start the SSE server + open browser
dotnet run --project src/cli/GitLabSummary -- serve --group my-org --open

# In another terminal, start the Vue dev server
cd src/dashboard
npm install
npm run dev
# → http://localhost:3000 (proxies API to localhost:5100)

# Or build and serve from CLI (port 5100 serves built dashboard)
npm run build
# Restart serve command → http://localhost:5100

One liner

You must pull the repo 1st and install the gitlab-summary tool from nuget as shown above

To run from one line:

(cd src/dashboard && npm run dev) & (cd ../.. && gitlab-summary serve --group 2217 --open)

Dashboard Usage

• Change Group: Type group ID in top bar or click tree icon to browse hierarchy
• Change Period: Select from dropdown (1d, 3d, 7d, 14d, 30d)
• View Pipeline Details: Click any pipeline row to see jobs and logs
• Analyze Failures: Click "Analyze with AI" on failed jobs (requires GitHub Copilot)
• View Contributors: Click any username to see their statistics
• Customize AI Prompt: Click settings icon → modify system prompt for AI analysis

CLI Reference

token set [--url <URL>]

Store or update your GitLab access token. Prompts for masked input.

token show

Display the stored token (masked) and configured GitLab URL.

token clear

Remove the stored token.

url set --url <URL>

Set the GitLab instance URL.

url show

Display the configured GitLab URL.

pipelines --group <GROUP> [OPTIONS]

Show pipeline activity summary.

serve --group <GROUP> [OPTIONS]

Start SSE dashboard server.

API Endpoints (Serve Mode)

Core Endpoints

Settings Endpoints

Group Hierarchy Endpoints

AI Analysis Endpoints

Job Trace Endpoint

Project Structure

src/
├── cli/                    # .NET 10 Console App
│   ├── GitLabSummary/      # Main project
│   │   ├── Commands/       # CLI command handlers
│   │   ├── Models/         # Data models
│   │   ├── Services/       # API client, aggregation, credentials, AI
│   │   ├── Rendering/      # Spectre.Console output formatters
│   │   └── Configuration/  # App settings
│   └── GitLabSummary.Tests/
└── dashboard/              # Vite + Vue 3 + Vuetify
    └── src/
        ├── composables/    # SSE stream, AI analysis, formatters
        ├── components/     # Vue components (dialogs, detail views)
        ├── pages/          # Route pages (Overview, Projects, Contributors)
        └── types/          # TypeScript interfaces

## Configuration

### Token Storage
Tokens are stored securely using platform-specific APIs:
- **macOS**: Keychain
- **Windows**: DPAPI (Data Protection API)
- **Linux**: .NET DataProtection with file-based key storage

### Settings File
Located at `~/.gitlab-summary/settings.json`:
```json
{
  "GitLabUrl": "https://gitlab.example.com"
}

AI Analysis Cache

Located at ~/.gitlab-summary/ai-analysis-cache.json — stores analysis results per job.

License

MIT