AgentSkillsCN

check-pipeline

检查 GitLab CI 管道状态，并排查失败原因。当用户询问 CI 状态、管道失败，或希望调试失败作业时，可使用此技能。

SKILL.md
--- frontmatter
name: check-pipeline
description: Check GitLab CI pipeline status and investigate failures. Use when user asks about CI status, pipeline failures, or wants to debug failed jobs.
allowed-tools:
  - Bash(~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh:*)
  - Bash(glab ci status:*)
  - Bash(glab mr list:*)
  - Bash(glab mr view:*)
  - Bash(git rev-parse:*)
  - Bash(git branch:*)
  - Read
  - Grep

Check GitLab CI Pipeline

Investigate GitLab CI pipeline status and debug failures.

Key Concept: MR Pipelines vs Branch Pipelines

GitLab often creates two pipelines for merge requests:

  1. •

    Branch Pipeline (ref: branch-name)

    • •Triggered by pushing to the branch
    • •Often runs only security scans or limited tests
    • •Status shown: "success" even when MR pipeline fails
  2. •

    MR Pipeline (ref: refs/merge-requests/<number>/head)

    • •Triggered by the merge request
    • •Runs the full test suite from .gitlab-ci.yml
    • •This is the one that matters for merge readiness

The helper script filters out source: "external" pipelines (security scans) automatically.

Helper Script

Use the allowlisted helper script for all API calls:

bash
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh <command> [args]

Commands:

  • •mr-pipelines <mr-number> - List pipelines for an MR
  • •branch-pipelines [branch] - List pipelines for a branch (defaults to current)
  • •pipeline-jobs <pipeline-id> - List all jobs in a pipeline
  • •failed-jobs <pipeline-id> - List only failed jobs
  • •job-trace <job-id> - Get job log output
  • •job-info <job-id> - Get job metadata
  • •pipeline-info <pipeline-id> - Get pipeline metadata

Investigation Workflow

Step 1: Find the MR

bash
# Get current branch
git rev-parse --abbrev-ref HEAD

# Find MR for this branch
glab mr list --source-branch $(git rev-parse --abbrev-ref HEAD)

Step 2: Get MR Pipelines

bash
# List pipelines for the MR (MR number from step 1)
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh mr-pipelines <mr-number>

Look at the output:

  • •Find pipelines where ref starts with refs/merge-requests/ - these are MR pipelines
  • •Check the status field: success, failed, running, pending
  • •Note the id of the failed pipeline

Step 3: Find Failed Jobs

bash
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh failed-jobs <pipeline-id>

This shows failed job names and URLs.

Step 4: Get Job Logs

bash
# Get full trace (may be large)
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-trace <job-id>

# Get last 200 lines
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-trace <job-id> | tail -200

# Search for errors
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-trace <job-id> | grep -E "(FAIL|Error|error:|failed)" | head -30

Step 5: Get Job Details

bash
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-info <job-id>

Returns: id, name, status, failure_reason, started_at, finished_at, duration, web_url

Common Patterns

Quick Status Check

bash
glab ci status

Shows current branch pipeline status (but remember: this may show branch pipeline, not MR pipeline).

Check if Branch Pipeline Passed but MR Pipeline Failed

This is common! The branch pipeline may run only security scans while the MR pipeline runs full tests.

bash
# Compare branch vs MR pipelines
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh branch-pipelines
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh mr-pipelines <mr-number>

Find Test Failures in Logs

Job logs can be large and truncated. Search strategically:

bash
# Look for test failures
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-trace <job-id> | grep -E "(FAIL|✗|×|Test Files.*failed)" | head -20

# Look for build errors
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-trace <job-id> | grep -E "(Error:|error:|ELIFECYCLE|exit code)" | head -20

# Get context around errors
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-trace <job-id> | grep -B5 -A10 "FAIL" | head -50

Check Pipeline Source

bash
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh pipeline-info <pipeline-id> | jq -r '.source'

Common sources:

  • •push - triggered by git push
  • •merge_request_event - triggered by MR
  • •external - security scan (Semgrep, etc.) - usually ignore these

Integration Tests vs Unit Tests

In this monorepo:

  • •Unit tests: Run in CI and should pass
  • •Integration tests: Connect to real services, can be flaky, may be configured to not block

If integration tests fail but unit tests pass, check if integration test failures block the pipeline.

Retry a Pipeline

If you suspect a flaky failure, push an empty commit to retrigger:

bash
git commit --allow-empty -m "Retrigger CI"
git push

Then watch the new pipeline.

Example Session

code
User: "CI failed, can you check what went wrong?"

Claude: Let me check the pipeline status for your branch.

# Find the MR
glab mr list --source-branch $(git rev-parse --abbrev-ref HEAD)
# Output: !4674 modernize-document-context

# Get MR pipelines
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh mr-pipelines 4674
# Output shows pipeline 4467641 failed

# Find failed jobs
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh failed-jobs 4467641
# Output: unit tests: failed - https://...

# Get logs
~/.claude/skills/check-pipeline/scripts/glab-pipeline.sh job-trace 62708639 | tail -200
# Analyze the failure...