| name | monitor-pipeline |
| description | Monitor a GitLab pipeline or job until completion, reporting status changes and failures in real-time |
Monitor GitLab Pipeline
Name
gitlab:monitor-pipeline - Monitor a pipeline or job until completion with real-time status updates
Synopsis
/monitor-pipeline <project-id> <pipeline-id> [--job <job-id>] [--interval <seconds>]
Description
Continuously monitors a GitLab CI/CD pipeline or specific job until it reaches a terminal state (success, failed, or canceled). Reports status changes as they happen and immediately notifies the user of any failures with detailed error information.
Implementation
This skill uses a polling approach to monitor pipeline and job statuses:
- Initial Status Check: Fetch current pipeline/job state
- Polling Loop: Check status at regular intervals (default: 15 seconds)
- Change Detection: Compare current state with previous state
- Real-time Reporting: Output updates when jobs transition states
- Failure Notification: Immediately report failures with job logs
- Completion: Exit when pipeline reaches terminal state
Monitoring Algorithm
WHILE pipeline.status IN [pending, running, waiting_for_resource, preparing]
WAIT interval seconds
FETCH current pipeline status
FETCH all job statuses
FOR each job:
IF job.status changed:
REPORT status change
IF job.status == "failed":
FETCH job logs
REPORT failure details immediately
REPORT overall progress summary
REPORT final pipeline result
Usage
Monitor a Pipeline
/monitor-pipeline 456 1234
Monitor a Specific Job
/monitor-pipeline 456 1234 --job 5678
Custom Polling Interval
/monitor-pipeline 456 1234 --interval 30
What This Skill Does
- Fetches initial pipeline state using GitLab API
- Tracks job transitions from pending -> running -> success/failed
- Reports immediately when any job fails
- Fetches failure logs automatically for failed jobs
- Provides progress updates showing completed vs remaining jobs
- Exits cleanly when pipeline completes or is canceled
Prerequisites
- GitLab MCP server must be configured
- Access to the target project
- Valid pipeline ID (can be obtained from MR or project pipelines list)
Example Interaction
Successful Pipeline Monitoring
User: /monitor-pipeline 456 1234
Claude: Starting pipeline monitor for Pipeline #1234 in project 456...
## Pipeline Monitor Started
**Pipeline**: #1234
**Branch**: feature/add-authentication
**Started**: 2025-01-15 10:30:22
**Status**: Running
I'll monitor this pipeline and report status changes as they happen.
---
### Update [10:31:45]
**Stage: build**
- ✓ `compile` completed successfully (1m 18s)
Progress: 1/6 jobs complete
---
### Update [10:32:30]
**Stage: build**
- ✓ `bundle-assets` completed successfully (42s)
Progress: 2/6 jobs complete
---
### Update [10:34:15]
**Stage: test**
- ✓ `unit-tests` completed successfully (1m 45s)
Progress: 3/6 jobs complete
---
### Update [10:36:00]
**Stage: test**
- ✓ `integration-tests` completed successfully (1m 45s)
Progress: 4/6 jobs complete
---
### Update [10:37:30]
**Stage: lint**
- ✓ `eslint-check` completed successfully (1m 30s)
- ✓ `type-check` completed successfully (1m 28s)
Progress: 6/6 jobs complete
---
## Pipeline Complete
**Status**: ✓ Success
**Total Duration**: 7m 08s
**All 6 jobs passed**
The pipeline completed successfully. Your changes are ready for merge.
Pipeline with Failure
User: /monitor-pipeline 456 1234
Claude: Starting pipeline monitor for Pipeline #1234...
## Pipeline Monitor Started
**Pipeline**: #1234
**Branch**: feature/database-migration
**Status**: Running
---
### Update [10:31:45]
**Stage: build**
- ✓ `compile` completed successfully (1m 18s)
Progress: 1/6 jobs complete
---
### FAILURE ALERT [10:33:20]
**Job Failed**: `integration-tests` in stage `test`
**Duration**: 1m 35s
**Exit Code**: 1
**Error Log**:
FAILED tests/integration/auth.test.ts
● Authentication API › POST /login › should validate credentials
ConnectionError: Connection to database refused
at PostgresClient.connect (src/db/client.ts:45:12)
at setupTestDB (tests/setup.ts:23:8)
1 test failed, 12 passed
**Likely Causes**:
1. Database service not available in CI environment
2. Missing DATABASE_URL environment variable
3. Network connectivity issues in test container
---
## Pipeline Failed
**Status**: ✗ Failed
**Duration**: 3m 35s
**Failed Jobs**: 1 (integration-tests)
**Passed Jobs**: 2
**Canceled Jobs**: 3
The pipeline failed due to test failures. Review the error above and push a fix.
Would you like me to help debug the database connection issue?
Monitoring a Specific Job
User: /monitor-pipeline 456 1234 --job 5678
Claude: Starting job monitor for Job #5678 (deploy-production)...
## Job Monitor Started
**Job**: deploy-production (#5678)
**Stage**: deploy
**Status**: Running
**Started**: 2025-01-15 14:30:00
---
### Progress [14:31:00]
Deploying to production cluster...
- Pulling latest images... done
- Running database migrations... done
- Starting new containers...
---
### Progress [14:32:30]
- Health checks passing (3/3 replicas)
- Draining old instances...
- Deployment complete!
---
## Job Complete
**Status**: ✓ Success
**Duration**: 2m 45s
Production deployment successful!
Arguments
| Argument | Required | Description |
|---|
project-id | Yes | Numeric project ID or URL-encoded path |
pipeline-id | Yes | Pipeline ID to monitor |
--job | No | Specific job ID to monitor instead of entire pipeline |
--interval | No | Polling interval in seconds (default: 15, min: 5, max: 300) |
Terminal States
The monitor exits when the pipeline/job reaches one of these states:
| State | Description |
|---|
success | All jobs completed successfully |
failed | One or more jobs failed |
canceled | Pipeline was manually canceled |
skipped | Pipeline was skipped (rules not met) |
Status Indicators
| Icon | Meaning |
|---|
| ✓ | Success/Passed |
| ✗ | Failed |
| ⏳ | Running |
| ⏸️ | Pending/Waiting |
| ⏭️ | Skipped |
| ⊘ | Canceled |
Tips
- Use shorter intervals (5-10s) for quick pipelines
- Use longer intervals (30-60s) for long-running deployments
- Monitor specific jobs when you only care about one stage
- The skill automatically fetches logs for failed jobs
- Cancel monitoring with Ctrl+C if needed
Error Handling
- API Errors: Retries with exponential backoff
- Network Issues: Reports connection problems, continues monitoring
- Invalid IDs: Exits immediately with helpful error message
- Permission Denied: Reports access issue, suggests checking permissions
Related Commands
/view-pipeline: One-time snapshot of pipeline status/create-mr: Create MR that triggers a pipeline/review-mr: Review MR including pipeline status
