Skip to content

🔧 [FEATURE] Add Pipeline Error Details Tool for Failed Pipeline Diagnostic

🔧 [FEATURE] Add Pipeline Error Details Tool for Failed Pipeline Diagnostics

🎯 Problem Statement

When GitLab pipelines fail with configuration errors or other issues, the standard pipeline API returns minimal information. The yaml_errors field is often null even when YAML errors exist, and configuration errors that prevent job creation provide no diagnostic information through the API.

🚨 Current Limitations

What We Get Now 

{
  "id": 1442,
  "status": "failed",
  "yaml_errors": null,
  "started_at": null,
  "duration": null
}

What We're Missing

  • Specific error messages for configuration failures
  • Detailed reasons for pipeline creation failures
  • Diagnostic information for "no jobs" scenarios
  • Runner allocation failures or quota issues

🔧 Proposed Solution

Implement get_pipeline_error_details tool that aggregates error information from multiple GitLab API endpoints to provide comprehensive pipeline failure diagnostics.

Technical Implementation

New Tool: get_pipeline_error_details

{ name: 'get_pipeline_error_details', description: 'Get detailed error information for failed pipelines including configuration errors', inputSchema: GetPipelineErrorDetailsSchema, handler: getPipelineErrorDetails }

Schema Definition

export const GetPipelineErrorDetailsSchema = ProjectParamsSchema.extend({ pipeline_id: z.number().describe('Pipeline ID to get error details for'), include_job_logs: z.boolean().optional().default(false), include_validation: z.boolean().optional().default(true) });

export const PipelineErrorDetailsSchema = z.object({ pipeline_id: z.number(), status: z.string(), error_type: z.enum(['configuration', 'job_failure', 'runner_issue', 'unknown']), errors: z.array(z.object({ source: z.string(), message: z.string(), details: z.any().optional() })), failed_jobs: z.array(z.object({ id: z.number(), name: z.string(), failure_reason: z.string(), log_excerpt: z.string().optional() })).optional(), suggestions: z.array(z.string()).optional() });

✅ Acceptance Criteria

  • Tool aggregates error data from pipeline, jobs, and validation endpoints
  • Identifies configuration errors vs runtime failures
  • Provides actionable error messages and suggestions
  • Handles "no jobs" pipeline scenarios
  • Returns runner/resource allocation issues
  • Comprehensive error categorization
  • Tests with ≥80% coverage
  • Documentation with examples

📊 Benefits

  • Complete Diagnostics: One tool for all pipeline error information
  • Faster Resolution: Actionable suggestions for common errors
  • Automation Support: Programmatic error handling in CI/CD workflows
  • Reduced Debugging Time: No need to check multiple endpoints

🔗 Related Context

Complements validate_ci_config for comprehensive CI/CD error handling.