ci-debugging

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

Output

Findings emitted by this skill (root-cause classifications, fix recommendations) MUST include a severity: field:

Severity	Meaning
S1	Block-merge: build broken, all checks failing, branch unmergeable
S2	Review-required: intermittent failure, platform-specific regression
S3	Advisory: warning-only, log noise, non-blocking dependency drift

When a finding's severity is ambiguous, default to S3 (advisory) per the false-positive playbook.