# GitHub Actions Debugging Guide

## Overview

The GitHub Actions debugging tool provides comprehensive analysis and reporting for CI/CD pipeline failures. It's designed to quickly identify and help resolve common issues, particularly JSON formatting problems in matrix generation.

## Quick Start

### Basic Usage

```bash
# Run basic debugging analysis
just gh-actions-debug

# Generate comprehensive report
just gh-actions-report

# Check recent failures quickly
just gh-actions-check
```

### Installation Requirements

- Python 3.8+
- GitHub CLI (`gh`) installed and authenticated
- Optional: `jq` for enhanced JSON processing
- Optional: `yq` for YAML validation

## Features

### 1. Comprehensive Analysis

The tool analyzes multiple aspects of GitHub Actions failures:

- **Failed Runs Analysis**: Lists recent failures with details
- **JSON/Matrix Issues**: Detects and validates JSON formatting problems
- **Workflow File Analysis**: Scans workflow files for common issues
- **Environment Configuration**: Checks secrets, variables, and settings
- **Performance Metrics**: Analyzes cache usage and artifacts

### 2. Focused Debugging

Target specific areas of concern:

```bash
# Focus on JSON/Matrix issues
just gh-actions-debug-json

# Analyze workflow files only
just gh-actions-debug-workflows

# Debug specific run
just gh-actions-debug-run 123456789
```

### 3. Report Generation

Generates detailed markdown reports with:

- Executive summary
- Quick statistics
- Detailed error analysis
- Recommendations and fixes
- Raw data export

## Common Use Cases

### Case 1: JSON Matrix Generation Errors

**Symptoms**: 
- "Invalid JSON" errors
- "Unexpected token" in matrix generation
- Empty matrix causing job failures

**Solution**:
```bash
# Analyze JSON issues
just gh-actions-debug-json

# Test matrix generation locally
just gh-actions-test-matrix

# Review suggested fixes in the report
```

### Case 2: Workflow Syntax Issues

**Symptoms**:
- Workflow fails to start
- YAML parsing errors
- Invalid workflow configuration

**Solution**:
```bash
# Validate specific workflow
just gh-actions-validate ci.yml

# Analyze all workflows
just gh-actions-debug-workflows
```

### Case 3: Recent Regression

**Symptoms**:
- Workflows that previously passed now fail
- Changes in behavior after commits

**Solution**:
```bash
# Generate full analysis
just gh-actions-debug-full

# Review recent commits section in report
# Check for workflow file changes
```

## Command Reference

### Analysis Commands

| Command | Description |
|---------|-------------|
| `gh-actions-debug` | Run basic debugging analysis |
| `gh-actions-debug-full` | Comprehensive analysis with verbose output |
| `gh-actions-debug-run ID` | Debug specific workflow run |
| `gh-actions-debug-json` | Focus on JSON/Matrix issues |
| `gh-actions-debug-workflows` | Analyze workflow files only |
| `gh-actions-report` | Generate and open detailed report |

### Quick Check Commands

| Command | Description |
|---------|-------------|
| `gh-actions-check` | List recent failures |
| `gh-actions-logs` | View latest failed run logs |
| `gh-actions-job-logs ID JOB` | View specific job logs |
| `gh-actions-watch` | Watch runs in real-time |

### Workflow Management

| Command | Description |
|---------|-------------|
| `gh-actions-rerun` | Re-run latest failed workflow |
| `gh-actions-rerun-id ID` | Re-run specific workflow |
| `gh-actions-cancel` | Cancel all running workflows |

### Validation & Testing

| Command | Description |
|---------|-------------|
| `gh-actions-list-workflows` | List all workflow files |
| `gh-actions-validate FILE` | Validate workflow YAML syntax |
| `gh-actions-test-matrix` | Test matrix generation locally |

## Python Script Options

The underlying Python script (`scripts/gh_actions_debug.py`) supports additional options:

```bash
# Direct script usage
python scripts/gh_actions_debug.py [OPTIONS]

Options:
  -o, --output-dir PATH     Output directory for reports (default: debug-reports)
  -r, --repo REPO          Repository to analyze (default: current)
  --run-id ID              Specific run ID to analyze
  -l, --limit N            Number of failed runs to analyze (default: 20)
  -v, --verbose            Enable verbose output
  --no-parallel            Disable parallel processing
  --export-artifacts       Export artifacts from failed runs
  --focus AREA             Focus on specific area: json, matrix, env, workflows, all
```

## Report Structure

Generated reports include:

1. **Executive Summary**
   - Generation timestamp
   - Repository information
   - Quick statistics

2. **Repository Overview**
   - Basic repository info
   - Available workflows

3. **Failed Runs Analysis**
   - Table of recent failures
   - Run details and metadata

4. **JSON Formatting Issues**
   - Error patterns detected
   - Matrix validation results
   - Context around errors

5. **Workflow Files Analysis**
   - Issues detected in each file
   - Matrix generation sections
   - Common problem patterns

6. **Recommendations**
   - Immediate action items
   - Common fixes with examples
   - Best practices

## Best Practices

### 1. Regular Monitoring

```bash
# Set up daily checks
0 9 * * * just gh-actions-check

# Weekly comprehensive reports
0 9 * * 1 just gh-actions-report
```

### 2. Clean Up Old Reports

```bash
# Remove reports older than 7 days
just gh-actions-clean-reports
```

### 3. Integration with Development

- Run `gh-actions-debug` after workflow failures
- Include report generation in incident response
- Share reports with team for collaborative debugging

## Troubleshooting

### Issue: "GitHub CLI not authenticated"

**Solution**:
```bash
gh auth login
```

### Issue: "jq not found" warning

**Solution**:
```bash
# Install jq for better JSON processing
# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq
```

### Issue: Reports not opening automatically

**Solution**:
Reports are saved in `debug-reports/` directory. Open manually:
```bash
ls -t debug-reports/github_actions_debug_*.md | head -1
```

## Common Fixes

### JSON Matrix Generation

**Problem**: Invalid JSON in matrix output

**Fix**:
```yaml
# Instead of:
echo "matrix=$JSON" >> $GITHUB_OUTPUT

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

### Empty Matrix Handling

**Problem**: Empty component list causes invalid JSON

**Fix**:
```yaml
# Add validation
MATRIX_JSON=$(echo "$COMPONENTS" | jq -Rs 'split("\n") | map(select(length > 0)) | map({name: ., path: .}) | {include: .}')

# Validate before output
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
```

### Shell Variable Escaping

**Problem**: Special characters in variables break JSON

**Fix**:
```yaml
# Use jq for proper escaping
SAFE_JSON=$(echo "$VAR" | jq -Rs .)
```

## Advanced Usage

### Custom Analysis Scripts

Create custom analysis by extending the debugger:

```python
from scripts.gh_actions_debug import GitHubActionsDebugger, DebugConfig

config = DebugConfig(
    focus_on="json",
    verbose=True,
    limit=50
)

with GitHubActionsDebugger(config) as debugger:
    debugger.run_analysis()
```

### Automated Fixes

While the tool provides recommendations, always review before applying:

```bash
# Create backup before attempting fixes
just gh-actions-fix-matrix workflow.yml

# Review and apply fixes manually
```

## Contributing

To improve the debugging tool:

1. Add new analysis patterns in `_analyze_workflow_content()`
2. Extend issue detection in `analyze_json_issues()`
3. Add new report sections in respective methods
4. Submit PR with test cases

## Related Documentation

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [GitHub CLI Manual](https://cli.github.com/manual/)
- [Project CI/CD Guide](../ci_cd_guide.md)