gitlab-ci-debugger
Debug and monitor GitLab CI/CD pipelines for merge requests. Check pipeline status, view job logs, and troubleshoot CI failures. Use this when the user needs to investigate GitLab CI pipeline issues, check job statuses, or view specific job logs.
When & Why to Use This Skill
This Claude skill provides a powerful interface for debugging and monitoring GitLab CI/CD pipelines directly within your workflow. It streamlines the troubleshooting process by allowing users to check merge request pipeline statuses, retrieve detailed job logs, and analyze failures, significantly reducing the time spent navigating the GitLab UI for DevOps tasks.
Use Cases
- Real-time monitoring of GitLab Merge Request pipeline statuses to ensure code quality before merging.
- Quickly identifying and isolating failed jobs within complex multi-stage CI/CD pipelines.
- Retrieving and analyzing specific job logs to diagnose build errors, test failures, or environment issues.
- Troubleshooting CI/CD pipeline failures by providing Claude with full log context for automated error analysis and fix suggestions.
| name | gitlab-ci-debugger |
|---|---|
| description | Debug and monitor GitLab CI/CD pipelines for merge requests. Check pipeline status, view job logs, and troubleshoot CI failures. Use this when the user needs to investigate GitLab CI pipeline issues, check job statuses, or view specific job logs. |
| allowed-tools | Bash, Read |
GitLab CI Debugger
This skill helps debug and monitor GitLab CI/CD pipelines associated with merge requests. It can check pipeline status, display job information grouped by stage, and retrieve logs for specific jobs.
This skill enables Claude to investigate GitLab CI pipeline failures by:
- Checking the current branch's MR pipeline status
- Identifying failed jobs
- Retrieving failed job logs
- Analyzing error messages and suggesting fixes
Prerequisites
Required tools (verify that these exist):
uvpackage manager- If not installed, instruct the user to run
pip install uvorcurl -LsSf https://astral.sh/uv/install.sh | sh
- If not installed, instruct the user to run
The script also requires the following configuration:
- Git repository with GitLab remote configured
- GitLab authentication via GITLAB_TOKEN env var or .netrc file
The script will fail if it detects any missing configuration. Interpret the error message and provide instructions for setting up the required configuration.
Instructions
When the user asks to check CI status, debug pipeline failures, or view job logs:
Check Current Pipeline Status
- Use the
check_mr_pipeline.pyscript without arguments to check the current branch's MR pipeline status - The script will display all jobs grouped by stage with status indicators
- Use the
Check Specific Branch
- If the user asks to check on the pipeline status for a different branch than the current one, use the
-bor--branchoption to specify that branch.- Example:
./check_mr_pipeline.py -b feature-branch
- Example:
- If the user asks to check on the pipeline status for a different branch than the current one, use the
View Job Logs
- Use the
-jor--joboption to retrieve and display logs for a specific job - Example:
./check_mr_pipeline.py -j "test-job-name" - The script will show the job's metadata and full log output
- Use the
Troubleshoot CI Failures
- If the user asks to troubleshoot a CI failure, use the full log output of a job to identify the error and suggest fixes.
Troubleshooting
- No open merge request found: Ensure there's an open MR for the branch
- Authentication errors when running the script: Instruct user to set up GITLAB_TOKEN or .netrc file
- Job not found: Use the script without
-joption first to see available job names - Script requires uv: The script uses
uv run --scriptto install dependencies and run the script. Ensure thatuvis installed.