Quick Start link

Get up and running with gitlab-summary in just a few minutes.

Quick Start with Docker (Easiest) link

The fastest way to start using gitlab-summary:

1. Create Configuration link

  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 link

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

3. Start the Dashboard link

  docker-compose up -d
  

4. Access the Dashboard link

Open http://localhost:5100 in your browser.

Done! 🎉 Your dashboard is now running.

📚 See Docker Deployment Guide for detailed configuration and troubleshooting.

Quick Start with CLI Tool link

If you prefer the command-line tool:

Prerequisites link

• ✅ Installed gitlab-summary (Installation Guide)
• ✅ GitLab access token with read_api scope
• ✅ GitLab group ID or path you want to monitor

Step 1: Configure Your Token link

Store your GitLab token securely:

  gitlab-summary token set --url https://gitlab.example.com
  

Enter your token when prompted (input is masked).

Step 2: View Pipeline Summary (CLI) link

Get a quick overview of all pipelines in your group:

  gitlab-summary pipelines --group my-org
  

Example output:

  GitLab Pipeline Summary (Last 24 hours)
Group: my-org

Project             Total  Success  Partial  Failed  Running  Duration  Pass Rate  Latest Run         Status
───────────────────────────────────────────────────────────────────────────────────────────────────────────
api-service           45      40        2       2        1    12m 30s      93.3%   01/15 14:32        ✅
web-frontend          38      33        2       3        0     8m 45s      92.1%   01/15 14:28        ⚠
mobile-app            25      22        1       1        1    15m 20s      92.0%   01/15 14:25        ⏳
database-migrations   18      18        0       0        0     2m 10s     100.0%   01/15 14:20        ✅
───────────────────────────────────────────────────────────────────────────────────────────────────────────
TOTAL               126     113        5       6        2    38m 45s      93.7%
  

📸 Screenshot placeholder: cli-pipelines-summary.png Description: Terminal showing CLI pipeline summary with project-level statistics including success rates, durations, partial success counts, latest run timestamps, and status icons

New features shown:

• Partial column: Shows pipelines with mixed job outcomes (some pass, some fail/cancel)
• Latest Run: Timestamp of most recent pipeline per project
• Status: Visual indicator of latest pipeline (✅ success, ⚠ partial, ❌ failed, ⏳ running, ⊘ canceled)

Step 3: View Detailed Breakdown link

See per-pipeline details with the --detailed flag:

  gitlab-summary pipelines --group my-org --detailed
  

Example output:

  api-service (45 pipelines)
──────────────────────────────────────────────────────────────────────────
Pipeline #12345  main          success  8m 30s   John Doe       fix: update API
Pipeline #12344  feature/auth  failed   12m 15s  Jane Smith     feat: add OAuth
Pipeline #12343  main          success  7m 45s   John Doe       docs: update README
...
  

📸 Screenshot placeholder: cli-pipelines-detailed.png Description: Terminal showing detailed per-pipeline breakdown with branch, status, duration, author, and commit message

Step 4: Filter by Time Range link

Customize the time window:

  # Last 30 minutes
gitlab-summary pipelines --group my-org --since 30m

# Last 12 hours
gitlab-summary pipelines --group my-org --since 12h

# Last 2 days
gitlab-summary pipelines --group my-org --since 2d

# Last 7 days
gitlab-summary pipelines --group my-org --since 7d
  

Supported formats:

• Minutes: 30m, 45m, 90m
• Hours: 1h, 12h, 24h
• Days: 1d, 2d, 7d, 14d, 30d

Step 5: Filter by Project link

Focus on a specific project:

  gitlab-summary pipelines --group my-org --project api-service
  

Supports partial matching:

  # Matches "api-service", "api-gateway", etc.
gitlab-summary pipelines --group my-org --project api
  

Step 6: Auto-Refresh with Watch Mode link

Monitor pipelines continuously with automatic refresh:

  # Refresh every 30 seconds
gitlab-summary pipelines --group my-org --watch 30

# Refresh every 2 minutes
gitlab-summary pipelines --group my-org --watch 2m

# Detailed view with 1 minute refresh
gitlab-summary pipelines --group my-org --detailed --watch 1m
  

Watch mode features:

• Live countdown timer showing seconds until next refresh
• Updates in-place without scrolling
• Press Ctrl+C to exit
• Supports seconds (30, 45s), minutes (1m, 5m), hours (1h)
• Minimum interval: 5 seconds

Example countdown display:

  Next update in 27s... (Ctrl+C to exit)
  

📸 Screenshot placeholder: cli-watch-mode-quickstart.png Description: Terminal showing watch mode in action with pipeline summary and countdown timer

Step 7: Launch the Dashboard link

Start the real-time web dashboard:

  gitlab-summary serve --group my-org --open
  

This will:

1. Start the SSE server on http://localhost:5100
2. Open your default browser automatically
3. Display real-time pipeline updates

Dashboard features:

• Live pipeline status updates
• Drill down into job logs
• AI-powered failure analysis
• Contributor statistics
• Group hierarchy navigation
• Commit timestamps and clickable links
• Partial success tracking

Common Workflows link

Monitor a Specific Project link

  gitlab-summary pipelines --group my-org --project api-service --since 12h --detailed
  

Quick Health Check link

  gitlab-summary pipelines --group my-org --since 1h
  

Shows recent activity and failures.

Long-term Analysis link

  gitlab-summary pipelines --group my-org --since 30d
  

View trends over the past month.

Dashboard with Custom Port link

  gitlab-summary serve --group my-org --port 8080
  

Access at http://localhost:8080

Auto-refresh Interval link

  gitlab-summary serve --group my-org --interval 60
  

Updates every 60 seconds (default: 30 seconds)

AI Model Selection link

  gitlab-summary serve --group my-org --ai-model claude-opus-4
  

Use a different Copilot model for AI analysis (default: claude-sonnet-4-5)

Finding Your Group ID link

Not sure of your group ID or path?

Option 1: From GitLab URL link

When viewing your group in GitLab, the URL contains the group path:

  https://gitlab.example.com/groups/my-org/subgroup
                                    └─────────┘
                                    group path
  

Option 2: From Group Settings link

1. Navigate to your group in GitLab
2. Go to Settings → General
3. Look for Group ID (numeric) or Group path

Option 3: Try the Dashboard link

  gitlab-summary serve --group 1 --open
  

Once open, use the group browser (tree icon) to navigate to the correct group.

Dashboard Quick Tour link

1. Overview Page link

Shows aggregate statistics:

• Total pipelines, success rate, in-progress count
• Timeline chart with status distribution
• Top contributors
• Failed jobs list

2. Projects Page link

Lists all projects with:

• Pipeline counts and pass rates
• Recent pipeline status
• AI analysis indicators (if failures analyzed)

3. Pipeline Details link

Click any pipeline to view:

• Job list with status and duration
• Job logs (all statuses)
• Commit information
• AI analysis (for failed jobs)

4. Group Switching link

Change groups without restarting:

1. Type group ID in the top input field
2. Or click the tree icon to browse hierarchy
3. Select desired group

5. AI Analysis link

For failed jobs:

1. Click the pipeline to view details
2. Find the failed job
3. Click Analyze with AI
4. View analysis, ask follow-up questions
5. Cached for instant re-access

Tips & Tricks link

Alias for Quick Access link

Add to your shell profile:

  # ~/.bashrc or ~/.zshrc
alias gls='gitlab-summary pipelines --group my-org'
alias glsd='gitlab-summary pipelines --group my-org --detailed'
alias glss='gitlab-summary serve --group my-org --open'
  

Usage:

  gls              # Quick summary
glsd --since 12h # Detailed view, last 12 hours
glss             # Launch dashboard
  

Dashboard in Development Mode link

For dashboard development:

  # Terminal 1: Start server
gitlab-summary serve --group my-org

# Terminal 2: Start Vue dev server
cd src/dashboard
npm run dev
  

Access at http://localhost:3000 (hot reload enabled)

One-liner (Development) link

From the repository root:

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

What’s Next? link

Explore CLI Commands link

• CLI Reference — Complete command documentation
• Token Management — Manage stored tokens
• URL Configuration — Configure GitLab instance

Learn the Dashboard link

• Dashboard Overview — Dashboard features
• AI Analysis — Use AI for failure analysis
• Group Navigation — Navigate complex hierarchies

Advanced Usage link

• API Reference — Integrate with other tools
• Troubleshooting — Common issues and solutions
• Development Guide — Contribute to gitlab-summary

Getting Help link

Issues link

Encountered a bug? Open an issue

Discussions link

Have questions? Start a discussion

Source Code link

View the source: github.com/garrardkitchen/gitlab-summary

See Also link

• Installation — Install gitlab-summary
• Configuration — Set up tokens
• CLI Reference — All commands
• Dashboard Guide — Web interface features