GitLabSummaryCLI 0.2.7

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, durations, latest run time, and status per project
• CLI Watch Mode — Auto-refresh with live countdown timer (e.g., --watch 30 or --watch 1m)
• 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 (seconds/minutes/hours/days)
• Subgroup Support — Includes nested subgroups by default
• Comprehensive Documentation — Full Hugo-based docs site with guides, examples, and use cases

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
• Commit Timestamps and Links — View commit date/time and click SHA to open in GitLab from pipeline details
• 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: Docker (Easiest)

Run the dashboard with Docker in seconds:

Using docker-compose (Recommended):

# 1. Create .env file with your tokens
cat > .env << EOF
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_URL=https://gitlab.example.com
GITLAB_GROUP=your-group-id
GH_TOKEN=github_pat_your_token_here
EOF

# 2. Download docker-compose.yml
curl -O https://raw.githubusercontent.com/garrardkitchen/gitlab-summary/main/docker-compose.yml

# 3. Start the dashboard
docker-compose up -d

# 4. Access the dashboard
open http://localhost:5100

Using docker run:

# Linux/Windows - named volume (Docker manages storage location)
docker run -d \
  --name gitlab-summary \
  -p 5100:5100 \
  -e GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" \
  -e GITLAB_URL="https://gitlab.example.com" \
  -e GITLAB_GROUP="your-group-id" \
  -e GH_TOKEN="github_pat_your_token_here" \
  -v gitlab-summary-data:/home/ubuntu/.local/share/gitlab-summary \
  garrardkitchen/gitlab-summary:latest

# macOS - bind mount to specific directory
docker run -d \
  --name gitlab-summary \
  -p 5100:5100 \
  -e GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" \
  -e GITLAB_URL="https://gitlab.example.com" \
  -e GITLAB_GROUP="your-group-id" \
  -e GH_TOKEN="github_pat_your_token_here" \
  -v ~/.gitlab-summary:/home/ubuntu/.local/share/gitlab-summary \
  garrardkitchen/gitlab-summary:latest

# Access the dashboard at http://localhost:5100

📋 Token Setup:

• GitLab: Create token at Settings → Access Tokens with read_api scope
• GitHub (optional, for AI analysis): Create Fine-grained PAT at https://github.com/settings/tokens?type=beta
  • User permissions: Copilot Chat (Read), User copilot requests (Read), Gists (Read+Write)

📚 See Docker Documentation for detailed setup, production deployment, and troubleshooting.

Option 2: .NET Global Tool

dotnet tool install -g GitLabSummary

To update to the latest version:

dotnet tool update -g GitLabSummary

Option 3: 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 4: 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

With Docker

# Start the dashboard (assumes .env file exists)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the dashboard
docker-compose down

# Access at: http://localhost:5100

With CLI Tool

# 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

# Watch mode - auto-refresh every 30 seconds
gitlab-summary pipelines --group my-org --watch 30

# Watch mode - auto-refresh every 1 minute
gitlab-summary pipelines --group my-org --watch 1m --detailed

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

Documentation

📚 Complete Documentation Site

The full documentation includes:

Getting Started

• Installation Guide — Multiple installation options (global tool, executables, source)
• Configuration — Token setup and settings
• Quick Start — Step-by-step first use

CLI Reference

• Token Commands — Secure token management
• URL Commands — GitLab instance configuration
• Pipelines Command — Complete guide with:
  • Summary and detailed views
  • Watch mode with live countdown
  • Understanding effective status and partial_success
  • Filter options (time range, project)
  • 6 common use cases with real-world examples
• Serve Command — Dashboard server with:
  • SSE architecture explanation
  • Configuration options
  • Dashboard features overview
  • 5 common use cases

Dashboard Guide

• Overview — All dashboard features including:
  • Pipeline detail dialog with commit timestamps and links
  • Real-time updates via SSE
  • Theme and navigation preferences
  • Responsive design
• AI Analysis — Copilot-powered failure analysis
• Group Navigation — Hierarchy browser

Advanced Topics

• API Reference — REST endpoints
• Development — Contributing guide
• Security — Token storage and best practices
• Troubleshooting — Common issues

---

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.

Option	Description	Default
-g, --group	GitLab group ID or path	Required
-s, --since	Time range (30m, 24h, 7d)	24h
-p, --project	Filter by project name	—
-d, --detailed	Show per-pipeline details	false
-w, --watch	Auto-refresh every N seconds/minutes (30, 1m, 5m)	—
-u, --url	Override GitLab URL	Config value

serve --group <GROUP> [OPTIONS]

Start SSE dashboard server. Dashboard URL: http://localhost:5100 (or custom port)

Option	Description	Default
-g, --group	GitLab group ID or path	Required
-s, --since	Time range	24h
--port	Server port	5100
--open	Open browser automatically	false
--interval	Refresh interval (seconds)	30
--ai-model	Copilot model for AI analysis	claude-sonnet-4-5
-u, --url	Override GitLab URL	Config value

API Endpoints (Serve Mode)

Core Endpoints

Endpoint	Method	Description
/api/events/pipelines	GET	SSE stream of pipeline summaries
/api/pipelines/summary	GET	Current summary snapshot
/api/pipelines/{projectId}/details/{pipelineId}	GET	Pipeline job details
/api/health	GET	Health check
/api/version	GET	Version information
/api/avatar?url={url}	GET	Proxy for GitLab avatars

Settings Endpoints

Endpoint	Method	Description
/api/settings	GET	Get current group and period
/api/settings	POST	Update group and period (body: {group, since})

Group Hierarchy Endpoints

Endpoint	Method	Description
/api/groups/{groupIdOrPath}	GET	Get group details
/api/groups/{groupIdOrPath}/subgroups	GET	Get child groups
/api/groups/parent/{parentId}	GET	Get sibling groups by parent ID

AI Analysis Endpoints

Endpoint	Method	Description
/api/ai/analyse	POST	Analyze failed job (body: {projectId, pipelineId, jobId, jobName, stage, log?})
/api/ai/followup	POST	Ask follow-up question (body: {projectId, pipelineId, jobId, jobName, stage, question, log?, previousAnalysis?})
/api/ai/analyzed	GET	Get list of analyzed job IDs for project (query: projectId)
/api/ai/cache	GET	Get cached analysis (query: projectId, jobId)
/api/ai/cache	DELETE	Delete cached analysis (query: projectId, jobId)
/api/ai/system-prompt	GET	Get current AI system prompt
/api/ai/system-prompt	PUT	Update AI system prompt (body: {prompt})

Job Trace Endpoint

Endpoint	Method	Description
/api/jobtrace	GET	Get job log trace (query: projectId, jobId)

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