# GitHub Actions Debugging - Quick Reference

## 🚀 Most Common Commands

```bash
# 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
```bash
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
```bash
just gh-actions-debug-json         # JSON/Matrix issues only
just gh-actions-debug-workflows    # Workflow files only
```

### Quick Checks
```bash
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

```bash
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

```bash
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

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

## 💡 Common Fixes

### Fix Matrix JSON Output
```yaml
# Bad:
echo "matrix=$JSON" >> $GITHUB_OUTPUT

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

### Handle Empty Arrays
```yaml
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
```yaml
echo "$MATRIX_JSON" | jq . > /dev/null || {
  echo "Invalid JSON generated"
  echo 'matrix={"include":[]}' >> $GITHUB_OUTPUT
  exit 0
}
```

## 🛠️ Direct Script Usage

```bash
# 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

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