---

name: ci-debugging description: Provides systematic CI/CD failure diagnosis and resolution. Use when CI builds fail, GitHub Actions errors occur, TLS/auth issues block pipelines, or platform-specific failures need debugging. allowed-tools: Bash, Read, Grep, Glob, WebFetch

CI/CD Debugging Skill

When to Use

• CI build failures
• GitHub Actions workflow errors
• TLS certificate or authentication issues
• Platform-specific compilation failures
• Dependency resolution problems

Diagnostic Flow

Step 1: Categorize Failure Type

Determine which category the failure falls into:

| Category | Indicators | Priority | |----------|------------|----------| | Environment/Auth | TLS errors, token expired, permission denied | Check first | | Platform-Specific | Works on Linux fails on Windows, vice versa | Check second | | Missing Dependencies | Module not found, package missing | Check third | | Actual Code Bug | Test assertions, logic errors | Check last |

Step 2: Environment/Auth Issues

Check for sandboxed environment limitations:

# Test GitHub API connectivity
curl -s --connect-timeout 5 https://api.github.com/zen

# Check GitHub CLI auth status
gh auth status

# Verify GITHUB_TOKEN
echo "Token present: ${GITHUB_TOKEN:+yes}"

Common Issues:

• TLS certificate errors -> Try diagnosis with connectivity check first
• Token expired -> Re-authenticate with gh auth login
• Sandbox blocked -> Use local git operations as fallback

Step 3: Platform-Specific Issues

Look for platform-specific patterns:

# Search for Unix-specific code
grep -rn "MSG_DONTWAIT\|/dev/null\|fork()" src/

# Check for Windows path issues
grep -rn '"/tmp\|"/var' src/

Fallback: Add conditional compilation or use cross-platform alternatives.

Step 4: Dependency Issues

# Check for missing packages (Node.js)
npm ls 2>&1 | grep "MISSING" || echo "No missing npm packages"

# For Python
pip check 2>&1 || echo "No pip issues"

# For CMake/C++
cmake --build build/ 2>&1 | grep -i "error\|not found" || echo "Build OK"

Step 5: Code Bug Analysis

If none of the above:

1. Read the failing test output carefully
2. Identify the assertion that failed
3. Trace back to the implementation
4. Fix the actual bug

Fallback Strategies

GitHub API Blocked

Priority order:
1. Use gh CLI (preferred)
2. Direct curl with GITHUB_TOKEN
3. Local git operations only
4. Manual intervention required

TLS/Certificate Issues

Priority order:
1. Check system certificates
2. Verify proxy settings
3. Use alternative connectivity check
4. Report as environment issue

Quick Commands

| Issue | Command | |-------|---------| | Check CI logs | gh run view --log-failed | | Re-run failed | gh run rerun --failed | | View workflow | gh run view | | Check auth | gh auth status | | List failed runs | gh run list --status failure |

Reference Documents (Import Syntax)

@./reference/common-failures.md