Use this guide to debug GitHub Agentic Workflows: download and analyze logs, audit runs, and trace workflow behavior.
# Download logs from the last 24 hours
gh aw logs --start-date -1d -o /tmp/workflow-logs
# Download logs for a specific workflow
gh aw logs weekly-research --start-date -1d
# Download logs with JSON output for programmatic analysis
gh aw logs --json
# 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
The gh aw logs command downloads workflow run artifacts and logs from GitHub Actions for analysis.
# 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
When you run gh aw logs, the following artifacts are downloaded for each run:
| File | Description |
|---|---|
aw_info.json | Engine configuration and workflow metadata |
safe_output.jsonl | Agent's final output content (when non-empty) |
agent_output/ | Agent logs directory |
agent-stdio.log | Agent standard output/error logs |
aw.patch | Git patch of changes made during execution |
workflow-logs/ | GitHub Actions job logs (organized by job) |
summary.json | Complete metrics and run data for all runs |
# 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")'
The gh aw audit command investigates a single workflow run in detail, downloading artifacts, detecting errors, and generating a report.
# 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
The audit command provides:
# 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
}'
Understanding the workflow architecture helps in debugging.
Agentic workflows use a markdown + YAML frontmatter format:
---
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
| Component | Purpose | Configuration |
|---|---|---|
| Engine | AI model to use | engine: copilot, claude, codex |
| Tools | APIs available to agent | tools: section with MCP servers |
| MCP Scripts | Context passed to agent | mcp-scripts: with GitHub expressions |
| Safe-Outputs | Resources agent can create | safe-outputs: with allowed operations |
| Permissions | GitHub token permissions | permissions: block |
| Network | Allowed network access | network: with domain/ecosystem lists |
# Compile workflow to GitHub Actions YAML
gh aw compile <workflow-name>
# Result: .github/workflows/<name>.md → .github/workflows/<name>.lock.yml
The .lock.yml file is the actual GitHub Actions workflow that runs.
Symptoms:
Solution: Add GitHub MCP server configuration:
tools:
github:
mode: remote
toolsets: [default]
Symptoms:
Solution: Add required permissions:
permissions:
contents: read
issues: write
pull-requests: write
Symptoms:
Solution: Configure mcp-scripts:
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 }}
Symptoms:
Solution: Enable safe-outputs:
safe-outputs:
staged: false # Set to false to actually create resources
create-issue:
labels: [ai-generated]
Symptoms:
Solution: Configure network access:
network:
allowed:
- defaults
- python # For PyPI
- node # For npm
- "api.example.com" # Custom domains
Symptoms:
Solution: Increase timeout or optimize prompt:
timeout-minutes: 30 # Increase from default
When a run is still executing:
# 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
| Command | Description |
|---|---|
gh aw logs | Download logs for all workflows |
gh aw logs <workflow> | Download logs for specific workflow |
gh aw logs --json | Output as JSON |
gh aw logs --start-date -1d | Filter by date |
gh aw logs --engine copilot | Filter by engine |
gh aw logs --parse | Generate Markdown reports |
| Command | Description |
|---|---|
gh aw audit <run-id> | Audit specific run |
gh aw audit <url> | Audit from GitHub URL |
gh aw audit <run-id> --json | Output as JSON |
gh aw audit <run-id> --parse | Parse logs to Markdown |
| Command | Description |
|---|---|
gh aw mcp list | List workflows with MCP servers |
gh aw mcp inspect <workflow> | Inspect MCP configuration |
| Command | Description |
|---|---|
gh aw status | Show all workflow status |
gh aw compile | Compile all workflows |
gh aw compile <workflow> | Compile specific workflow |
gh aw compile --strict | Compile with security checks |
| Command | Description |
|---|---|
gh aw run <workflow> | Trigger workflow manually |
gh workflow run <name>.lock.yml | Alternative trigger method |
gh run watch <run-id> | Monitor running workflow |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).