debugging-workflows

# Audit by run ID
gh aw audit 1234567890
 
# Audit from a GitHub Actions URL
gh aw audit https://github.com/owner/repo/actions/runs/1234567890
 
# Audit with JSON output
gh aw audit 1234567890 --json

# Download logs for all workflows (last 10 runs)
gh aw logs
 
# Download logs for a specific workflow
gh aw logs <workflow-name>
 
# Download with custom output directory
gh aw logs -o ./my-logs

# Filter by date range
gh aw logs --start-date 2024-01-01 --end-date 2024-01-31
gh aw logs --start-date -1w                    # Last week
gh aw logs --start-date -1mo                   # Last month
 
# Filter by AI engine
gh aw logs --engine copilot
gh aw logs --engine claude
gh aw logs --engine codex
 
# Filter by count
gh aw logs -c 5                                # Last 5 runs
 
# Filter by branch/tag
gh aw logs --ref main
gh aw logs --ref feature-xyz
 
# Filter by run ID range
gh aw logs --after-run-id 1000 --before-run-id 2000
 
# Filter firewall-enabled runs
gh aw logs --firewall                          # Only firewall-enabled
gh aw logs --no-firewall                       # Only non-firewall

# Generate JSON summary
gh aw logs --json
 
# Parse agent logs and generate Markdown reports
gh aw logs --parse
 
# Generate Mermaid tool sequence graph
gh aw logs --tool-graph
 
# Set download timeout
gh aw logs --timeout 300                       # 5 minute timeout

# Download failed runs from last week
gh aw logs --start-date -1w -o /tmp/debug-logs
 
# Check the summary for patterns
cat /tmp/debug-logs/summary.json | jq '.runs[] | select(.conclusion == "failure")'

# Audit by numeric run ID
gh aw audit 1234567890
 
# Audit from GitHub Actions URL
gh aw audit https://github.com/owner/repo/actions/runs/1234567890
 
# Audit from job URL (extracts first failing step)
gh aw audit https://github.com/owner/repo/actions/runs/1234567890/job/9876543210
 
# Audit from job URL with specific step
gh aw audit https://github.com/owner/repo/actions/runs/1234567890/job/9876543210#step:7:1

# JSON output for programmatic analysis
gh aw audit 1234567890 --json
 
# Custom output directory
gh aw audit 1234567890 -o ./audit-reports
 
# Parse agent logs and firewall logs
gh aw audit 1234567890 --parse
 
# Verbose output
gh aw audit 1234567890 -v

# Get detailed audit report
gh aw audit 1234567890 --json > audit.json
 
# Extract key information
cat audit.json | jq '{
  status: .status,
  conclusion: .conclusion,
  errors: .errors,
  missing_tools: .missing_tools,
  tool_usage: .tool_usage
}'

---
on:
  issues:
    types: [opened]
permissions:
  issues: write
timeout-minutes: 10
engine: copilot
tools:
  github:
    mode: remote
    toolsets: [default]
safe-outputs:
  create-issue:
    labels: [ai-generated]
---
 
# Workflow Title
 
Natural language instructions for the AI agent.
 
Use GitHub context like ${{ github.event.issue.number }}.

1. Trigger Event (issue opened, PR created, schedule, etc.)
     ↓
2. Activation Job
   - Validates permissions
   - Processes mcp-scripts
   - Sanitizes context
     ↓
3. AI Agent Job
   - Loads MCP servers and tools
   - Executes AI agent with prompt
   - Agent makes tool calls
   - Agent produces output
     ↓
4. Safe Outputs Job
   - Processes agent output
   - Creates GitHub resources (issues, PRs, etc.)
   - Applies labels, comments
     ↓
5. Completion
   - Workflow summary generated
   - Artifacts uploaded

# Compile workflow to GitHub Actions YAML
gh aw compile <workflow-name>
 
# Result: .github/workflows/<name>.md → .github/workflows/<name>.lock.yml

tools:
  github:
    mode: remote
    toolsets: [default]

permissions:
  contents: read
  issues: write
  pull-requests: write

mcp-scripts:
  issue:
    script: |
      return { title: process.env.ISSUE_TITLE, body: process.env.ISSUE_BODY };
    env:
      ISSUE_TITLE: ${{ github.event.issue.title }}
      ISSUE_BODY: ${{ github.event.issue.body }}

safe-outputs:
  staged: false  # Set to false to actually create resources
  create-issue:
    labels: [ai-generated]

# Summarize failed safe-output messages and types
gh aw audit <run-id>
 
# Include additional artifacts when diagnosis needs more context
gh aw audit <run-id> --artifacts usage,github-api,mcp,agent
 
# Escalate to full artifact collection for hard-to-classify failures
gh aw audit <run-id> --artifacts all
 
# Inspect full failing job logs to classify each message failure
gh run view <run-id> --job=<job-id> --log

network:
  allowed:
    - defaults
    - python    # For PyPI
    - node      # For npm
    - "api.example.com"  # Custom domains

timeout-minutes: 30  # Increase from default

# Poll until completion
while true; do
  output=$(gh aw audit <run-id> --json 2>&1)
  if echo "$output" | grep -q '"status":.*"\(completed\|failure\|cancelled\)"'; then
    echo "$output"
    break
  fi
  echo "⏳ Run still in progress. Waiting 45 seconds..."
  sleep 45
done

# Inspect MCP servers for a workflow
gh aw mcp inspect <workflow-name>
 
# List all workflows with MCP servers
gh aw mcp list

# Show status of all agentic workflows
gh aw status

# Download only the agent log artifact
GH_REPO=owner/repo gh run download <run-id> -n agent-stdio.log

# View specific job logs
gh run view <run-id>
gh run view --job <job-id> --log

# Parse firewall logs for network issues
gh aw logs --parse
 
# Check firewall-enabled runs
gh aw logs --firewall

# Compile with verbose output
gh aw compile --verbose
 
# Compile with strict security checks
gh aw compile --strict
 
# Run security scanners
gh aw compile --actionlint --zizmor --poutine