Quick Start

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

Prerequisites

Before you begin, ensure you have:

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

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)

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  Failed  Running  Duration  Pass Rate
──────────────────────────────────────────────────────────────────────────
api-service           45      42       2        1    12m 30s      93.3%
web-frontend          38      35       3        0     8m 45s      92.1%
mobile-app            25      23       1        1    15m 20s      92.0%
database-migrations   18      18       0        0     2m 10s     100.0%
──────────────────────────────────────────────────────────────────────────
TOTAL               126     118       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 and durations

Step 3: View Detailed Breakdown

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

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

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: Launch the Dashboard

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

Common Workflows

Monitor a Specific Project 

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

Quick Health Check 

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

Shows recent activity and failures.

Long-term Analysis 

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

View trends over the past month.

Dashboard with Custom Port 

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

Access at http://localhost:8080

Auto-refresh Interval 

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

Updates every 60 seconds (default: 30 seconds)

Finding Your Group ID

Not sure of your group ID or path?

Option 1: From GitLab URL

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

  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 

  gitlab-summary serve --group 1 --open

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

Dashboard Quick Tour

1. Overview Page

Shows aggregate statistics:

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

2. Projects Page

Lists all projects with:

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

3. Pipeline Details

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

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

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

Alias for Quick Access

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

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)

From the repository root:

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

What’s Next?

Explore CLI Commands

Learn the Dashboard

Advanced Usage

Getting Help

Issues

Encountered a bug? Open an issue

Discussions

Have questions? Start a discussion

Source Code

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

See Also