tomevault-io 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:
- Read the failing test output carefully
- Identify the assertion that failed
- Trace back to the implementation
- 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.