docs/workflow/gh_actions_debug_quickref.md

GitHub Actions Debugging - Quick Reference

🚀 Most Common Commands

# Quick failure check
just gh-actions-check

# Generate full debugging report
just gh-actions-report

# Debug JSON/Matrix issues
just gh-actions-debug-json

# Re-run failed workflow
just gh-actions-rerun

🔍 Debugging Commands

Basic Analysis

just gh-actions-debug              # Basic analysis
just gh-actions-debug-full         # Comprehensive (verbose, 50 runs)
just gh-actions-debug-run 12345    # Debug specific run ID

Focused Analysis

just gh-actions-debug-json         # JSON/Matrix issues only
just gh-actions-debug-workflows    # Workflow files only

Quick Checks

just gh-actions-check              # List 5 recent failures
just gh-actions-logs               # View latest failed logs
just gh-actions-job-logs ID JOB    # Specific job logs
just gh-actions-watch              # Real-time monitoring

🔄 Workflow Management

just gh-actions-rerun              # Re-run latest failed
just gh-actions-rerun-id 12345     # Re-run specific ID
just gh-actions-cancel             # Cancel all running

✅ Validation & Testing

just gh-actions-list-workflows     # List workflow files
just gh-actions-validate ci.yml    # Validate YAML syntax
just gh-actions-test-matrix        # Test matrix generation

📊 Reports & Maintenance

just gh-actions-report             # Generate & open report
just gh-actions-clean-reports      # Clean reports >7 days old

💡 Common Fixes

Fix Matrix JSON Output

# Bad:
echo "matrix=$JSON" >> $GITHUB_OUTPUT

# Good:
printf 'matrix=%s\n' "$JSON" >> "$GITHUB_OUTPUT"

Handle Empty Arrays

if [ -z "$MATRIX_JSON" ] || [ "$MATRIX_JSON" = '{"include":[]}' ]; then
  echo 'matrix={"include":[{"name":"default","path":"src"}]}' >> $GITHUB_OUTPUT
else
  echo "matrix=$MATRIX_JSON" >> $GITHUB_OUTPUT
fi

Validate JSON Before Output

echo "$MATRIX_JSON" | jq . > /dev/null || {
  echo "Invalid JSON generated"
  echo 'matrix={"include":[]}' >> $GITHUB_OUTPUT
  exit 0
}

🛠️ Direct Script Usage

# With options
python scripts/gh_actions_debug.py --verbose --limit 50 --focus json

# Export artifacts
python scripts/gh_actions_debug.py --export-artifacts

# Custom output directory
python scripts/gh_actions_debug.py -o /tmp/gh-debug

📁 Output Locations

• Reports: debug-reports/github_actions_debug_*.md
• Latest report: ls -t debug-reports/*.md | head -1

🔗 Prerequisites

• GitHub CLI: gh auth status
• Python 3.8+: python --version
• Optional: jq for JSON processing
• Optional: yq for YAML validation

❓ Help

just help-gh-actions               # Show all commands
just gh-actions-debug --help       # Script options