diagnose-ci-failures

name	diagnose-ci-failures
description	Diagnose GitLab CI failures for a MR, branch, pipeline ID, job ID, or GitLab pipeline URL using the GitLab CLI, extract error logs, and generate a plan to fix them. Use when the user asks to check CI status, pull CI issues, triage test failures, or investigate MR build failures.

diagnose-ci-failures

Programmatically diagnose CI failures and generate a plan to fix them.

Overview

This skill provides a deterministic workflow to check CI status, extract failure logs, analyze errors, and create a plan to resolve issues. The output is always a plan document that can be reviewed before execution.

This skill is diagnosis-only. Do not make code changes, commits, pushes, or merge requests.

Workflow

1. Locate the failing CI target

Determine the CI target from the user's input.

If the user provides a GitLab pipeline URL, extract the pipeline ID from the URL:

glab ci get --pipeline-id <pipeline-id> --with-job-details --output json

Example URL:

https://gitlab.com/GROUP/PROJECT/-/pipelines/PIPELINE_ID

If the user provides a pipeline ID directly:

glab ci get --pipeline-id <pipeline-id> --with-job-details --output json

If the user provides a branch name:

glab ci list --ref <branch> --status failed --per-page 5 --output json
glab ci get --pipeline-id <pipeline-id> --with-job-details --output json

If no branch, pipeline ID, job ID, or URL is provided, use the current checkout. First check whether the current branch has an associated MR:

glab mr view --output json

For a current MR branch, inspect the branch pipeline:

glab ci get --branch <branch> --with-job-details --output json

If the current branch does not have an associated MR, fall back to recent failed pipelines for the current branch:

git branch --show-current
glab ci list --ref <branch> --status failed --per-page 5 --output json
glab ci get --pipeline-id <pipeline-id> --with-job-details --output json

If no failed MR check or failed pipeline exists, report that no failing CI target was found and stop.

2. Check CI status

Fetch the status of all CI checks for the selected MR, branch, or run.

For a MR or branch pipeline:

glab ci get --branch <branch> --with-job-details --output json

For a pipeline:

glab ci get --pipeline-id <pipeline-id> --with-job-details --output json

Parse the output to identify:

• Completed checks
• In-progress checks
• Successful checks
• Failed checks, including names, pipeline IDs, job IDs, and details URLs when available

If CI is still running, inform the user which checks have already failed or passed, highlight checks still running, and suggest waiting for completion before final diagnosis.

3. Extract failure logs

For each failed job, pull the job trace:

glab ci trace <job-id> --pipeline-id <pipeline-id>

For deeper inspection when needed:

glab ci get --pipeline-id <pipeline-id> --with-job-details --output json
glab ci artifact <refName> <jobName> --output-dir .artifacts/<pipeline-id>

Focus on extracting:

• Error messages and locations, including file paths and line numbers
• Build or compilation errors
• Linting or formatting failures
• Test failure messages, failing test names, stack traces, and assertion output
• Environment or CI setup failures, such as missing secrets, permissions, unavailable services, dependency installation failures, or resource limits

4. Categorize errors

Group errors by type:

• Build/compilation errors: Type errors, syntax errors, missing imports, missing dependencies, incompatible versions, failed builds
• Test failures: Failing tests, assertion failures, snapshot mismatches, timeouts, integration failures, flaky-looking behavior
• Linting/formatting issues: Formatter failures, linter violations, unused code, style violations
• Environment issues: Missing secrets, permissions, unavailable services, CI image problems, dependency download failures, resource limits, platform-specific setup issues

When tools are language-specific, mention them only as observed facts from the logs, not as assumptions.

5. Generate fix plan

Create a plan document with:

• Problem Statement: Summary of failing checks or pipelines
• Current State: What errors were found, where they occur, and which checks are affected
• Root Cause Analysis: The most likely cause of each failure category, based on the logs
• Proposed Changes: Specific fixes needed for each error category
• Validation Steps: Commands or CI checks that should be run to verify the fixes

Do not implement the fixes. The plan should be specific enough for a follow-up implementation task.

Important Notes

• Always create a plan first. Never make code changes directly.
• Prefer evidence from CI logs over local assumptions.
• If tests fail locally but pass in CI, treat them as local/environment-specific unless CI logs show the same failure.
• If CI logs show multiple unrelated failures, group them and recommend fixing one category at a time.
• Avoid assuming a programming language, package manager, test framework, or build system until it is observed from repository files or CI logs.

Common CI Check Types

• Formatting and linting
• Unit tests
• Integration tests
• Build or package checks
• Platform-specific tests
• Deployment or artifact checks
• CI summary or required-status checks

Example Commands

Get failed checks for the current MR branch:

glab ci get --branch <branch> --with-job-details --output json

Get recent failed pipelines for a branch:

glab ci list --ref <branch> --status failed --per-page 5 --output json

Inspect a specific run:

glab ci get --pipeline-id <pipeline-id> --with-job-details --output json

Get failed logs from a specific run:

glab ci trace <job-id> --pipeline-id <pipeline-id>

Inspect a specific failed job:

glab ci trace <job-id> --pipeline-id <pipeline-id>