Pipelines Command

View pipeline activity summary and details for all projects in a GitLab group.

Usage:

  gitlab-summary pipelines --group <GROUP> [OPTIONS]

Options

Required

OptionShortDescriptionExample
--group-gGitLab group ID or pathmy-org, 123, parent/child

Optional

OptionShortDescriptionDefaultExample
--since-sTime range to query24h30m, 12h, 7d
--project-pFilter by project name (partial match)All projectsapi, frontend
--detailed-dShow per-pipeline breakdownfalseN/A (flag)
--watch-wAuto-refresh at intervalOff30, 1m, 5m
--url-uOverride GitLab instance URLConfig valuehttps://gitlab.com

Time Format

The --since and --watch options accept flexible time formats:

FormatDescriptionExamples
SecondsNumber with s suffix or bare number (watch only)30s, 45s, 90s, 30
MinutesNumber with m suffix5m, 30m, 90m
HoursNumber with h suffix1h, 12h, 24h
DaysNumber with d suffix1d, 7d, 14d, 30d

Summary View (Default)

Shows aggregate statistics per project with effective status (partial success for mixed job outcomes).

Example:

  gitlab-summary pipelines --group my-org

Output includes:

  • Total: Pipeline count per project
  • ✅ Pass: Fully successful pipelines (all jobs passed)
  • ⚠ Partial: Partial success (some jobs failed with allow_failure: true)
  • ❌ Fail: Failed pipelines
  • ⏳ Run: Currently running/pending
  • ⊘ Cancel: Canceled pipelines
  • Avg Duration: Average execution time
  • Latest Run: Date/time of most recent pipeline
  • Status: Icon showing latest pipeline status (✅ ⚠ ❌ ⏳ ⊘)

Example output:

  ┌──────────────────┬───────┬──────┬─────────┬──────┬─────┬────────┬──────────────┬─────────────┬────────┐
│ Project          │ Total │ Pass │ Partial │ Fail │ Run │ Cancel │ Avg Duration │ Latest Run  │ Status │
├──────────────────┼───────┼──────┼─────────┼──────┼─────┼────────┼──────────────┼─────────────┼────────┤
│ api-service      │   45  │  40  │    2    │  2   │  1  │   0    │   12m 30s    │ 02/10 14:22 │   ⚠    │
│ web-frontend     │   38  │  35  │    0    │  3   │  0  │   0    │    8m 45s    │ 02/10 13:15 │   ✅   │
└──────────────────┴───────┴──────┴─────────┴──────┴─────┴────────┴──────────────┴─────────────┴────────┘

📸 Screenshot placeholder: cli-summary-view.png Description: Terminal showing summary view with color-coded status columns and latest run information

Detailed View

Shows per-pipeline breakdown with the --detailed flag.

Example:

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

Output:

  api-service (45 pipelines)
──────────────────────────────────────────────────────────────────────────
Pipeline  Branch        Status           Duration  Author         Commit
#12345    main          success          8m 30s    John Doe       fix: update API
#12344    feature/auth  partial_success  12m 15s   Jane Smith     feat: add OAuth
#12343    main          failed           7m 45s    John Doe       docs: README
#12342    develop       running          --        Alice Chen     test: add tests
...

Columns explained:

  • Pipeline: Pipeline ID (can be used with --url to open in GitLab)
  • Branch: Git branch that triggered the pipeline
  • Status: Effective status (see status meanings below)
  • Duration: Total execution time (or -- if still running)
  • Author: User who triggered the pipeline
  • Commit: First line of commit message

Understanding Status Values

gitlab-summary shows effective status based on actual job outcomes, not just GitLab’s reported status:

StatusIconMeaningWhen It Appears
success✅All jobs passedEvery job in the pipeline succeeded
partial_success⚠Mixed resultsSome jobs failed/canceled but had allow_failure: true
failed❌Pipeline failedOne or more jobs failed without allow_failure
running⏳In progressPipeline is currently executing
pending⏳Waiting to startPipeline is queued
canceled⊘CanceledUser or system canceled the pipeline
skipped⊘SkippedPipeline was skipped (e.g., [skip ci])

Why “partial_success”?

GitLab may report a pipeline as “success” even when some jobs fail if those jobs have allow_failure: true set. gitlab-summary computes the effective status by analyzing all job outcomes, giving you a more accurate picture of your CI/CD health.

Example scenario:

  # .gitlab-ci.yml
lint:
  script: npm run lint
  allow_failure: true  # Won't block the pipeline

test:
  script: npm test

If lint fails but test passes:

  • GitLab status: success
  • gitlab-summary effective status: partial_success ⚠

This helps you catch issues that might otherwise be hidden.

Filter by Time Range

Last 30 minutes:

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

Last 12 hours:

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

Last 7 days:

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

Filter by Project

Exact match:

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

Partial match:

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

Matches api-service, api-gateway, etc.

Watch Mode (Auto-Refresh)

Continuously refresh the output at specified intervals with a live countdown timer.

Basic watch (30 seconds):

  gitlab-summary pipelines --group my-org --watch 30

Watch with 1 minute intervals:

  gitlab-summary pipelines --group my-org --watch 1m

Watch detailed view with 2 minute intervals:

  gitlab-summary pipelines --group my-org --watch 2m --detailed

Features:

  • Live countdown showing time until next refresh
  • Clear screen between updates for clean display
  • Accepts bare numbers as seconds (e.g., 30 = 30 seconds)
  • Accepts time format with units (e.g., 1m, 30s, 2h)
  • Minimum interval: 5 seconds
  • Press Ctrl+C to exit

Example output:

  [Pipeline data displayed here]

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

📸 Screenshot placeholder: cli-watch-mode.png Description: Terminal showing watch mode with pipeline data and countdown timer at bottom showing “Next update in 27s… (Ctrl+C to exit)”

Combined Filters

Detailed view, specific project, last 12 hours:

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

Watch mode with multiple filters:

  gitlab-summary pipelines --group my-org --project api --since 2d --detailed --watch 1m

Common Use Cases

1. Quick Status Check

Check the current state of all projects:

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

Use this for a quick health check at the start of your day or after a deployment.

2. Debug Specific Project

Focus on a single project with detailed pipeline information:

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

Shows every pipeline for api-service with branch, status, duration, author, and commit message.

3. Long-term Trend Analysis

View pipeline history over a longer period:

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

Useful for identifying patterns in success rates and performance over time.

4. Continuous Monitoring

Watch a critical project in real-time during a deployment or incident:

  gitlab-summary pipelines --group my-org --project production-api --watch 30 --detailed

Updates every 30 seconds, showing new pipelines as they run.

5. Team Dashboard

Run on a shared monitor in your office:

  gitlab-summary pipelines --group my-org --watch 2m

Refreshes every 2 minutes, showing team-wide pipeline health at a glance.

6. Partial Match Projects

Monitor multiple related projects:

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

Matches api-service, auth-service, payment-service, etc.