debugging-workflows

OverviewHistoryStatsSecurity

npx skills add github/gh-aw-firewall --skill debugging-workflows

Documentation

SKILL.md

npx skills add ...

Documentation

SKILL.md

Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.

npx skills add github/gh-aw-firewall --skill debugging-workflows

Documentation

SKILL.mdView source

Debugging Workflows Skill

Use this skill when you need to debug GitHub Actions workflows, download workflow logs or summaries, or understand how agentic workflows and the AWF firewall work together.

Quick Start

Download Workflow Logs

Use the download-workflow-logs.ts script to download logs from a workflow run:

# Download logs from the latest workflow run
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts
 
# Download logs from a specific run ID
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --run-id 1234567890
 
# Download logs from a specific workflow
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --workflow test-integration.yml
 
# Save logs to a specific directory
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --output ./my-logs

Download Workflow Summary

Use the download-workflow-summary.ts script to get a summary of workflow runs:

# Get summary of latest workflow runs
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts
 
# Get summary for a specific workflow run
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --run-id 1234567890
 
# Get summary for a specific workflow file
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --workflow test-integration.yml
 
# Get summary as JSON
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --format json

GitHub CLI Commands

The gh CLI is essential for debugging workflows. Here are the most useful commands:

List Workflow Runs

# List recent workflow runs
gh run list --limit 10
 
# List runs for a specific workflow
gh run list --workflow test-integration.yml --limit 10
 
# List only failed runs
gh run list --status failure --limit 10
 
# List runs in JSON format for parsing
gh run list --json databaseId,name,status,conclusion,createdAt --limit 10

View Workflow Run Details

# View a specific run
gh run view <run-id>
 
# View run with job details
gh run view <run-id> --verbose
 
# View run as JSON
gh run view <run-id> --json jobs,conclusion,status

Download Run Logs

# Download all logs for a run
gh run download <run-id>
 
# Download specific artifact
gh run download <run-id> --name <artifact-name>
 
# Download to specific directory
gh run download <run-id> --dir ./logs

Watch a Running Workflow

# Watch a workflow run in real-time
gh run watch <run-id>
 
# Watch with exit code (useful for CI)
gh run watch <run-id> --exit-status

Re-run Failed Jobs

# Re-run failed jobs only
gh run rerun <run-id> --failed
 
# Re-run all jobs
gh run rerun <run-id>

Understanding Agentic Workflows

What are Agentic Workflows?

Agentic workflows are GitHub Actions workflows that use AI agents (like GitHub Copilot or Claude) to perform tasks. They are defined using markdown + YAML frontmatter format in .github/workflows/*.md files and compiled to GitHub Actions YAML (.lock.yml files).

Key Components

Workflow File Format: .github/workflows/<name>.md
- YAML frontmatter for configuration
- Markdown body for AI instructions
- Compiles to .github/workflows/<name>.lock.yml
Triggers (on: field):
- Standard GitHub events: issues, pull_request, push, schedule
- Command triggers: /mention in issues/comments
- workflow_dispatch for manual triggers
Safe Outputs: Controlled way for AI to create GitHub entities
- create-issue: - Create GitHub issues
- create-pull-request: - Create PRs with git patches
- add-comment: - Add comments to issues/PRs
- add-labels: - Add labels to issues/PRs
- create-discussion: - Create GitHub discussions
Tools Configuration (tools: field):
- github: - GitHub API tools
- agentic-workflows: - Workflow introspection tools
- edit: - File editing tools
- web-fetch: / web-search: - Web access tools
- bash: - Shell command tools

Compiling Workflows

# Compile all workflows
gh aw compile
 
# Compile a specific workflow
gh aw compile <workflow-name>
 
# Compile with strict security checks
gh aw compile --strict

Debugging Agentic Workflows

# View status of all agentic workflows
gh aw status
 
# Download and analyze logs from previous runs
gh aw logs <workflow-name> --json
 
# Audit a specific run for issues
gh aw audit <run-id> --json

Common Issues

Missing Tool Calls: Check missing_tools in audit output
Safe Output Failures: Review safe_outputs.jsonl artifact
Permission Issues: Verify permissions: block in frontmatter
Network Blocked: Check network: configuration for allowed domains

Understanding the AWF Firewall

What is AWF?

AWF (Agent Workflow Firewall) is a tool that provides L7 (HTTP/HTTPS) egress control for GitHub Copilot CLI and other agents. It restricts network access to a whitelist of approved domains using Squid proxy and Docker containers.

Architecture Overview

┌─────────────────────────────────────────┐
│  Host (GitHub Actions Runner / Local)   │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │   Firewall CLI (awf)              │ │
│  │   - Parse arguments                │ │
│  │   - Generate Squid config          │ │
│  │   - Start Docker Compose           │ │
│  └────────────────────────────────────┘ │
│           │                              │
│           ▼                              │
│  ┌──────────────────────────────────┐   │
│  │   Docker Compose                 │   │
│  │  ┌────────────────────────────┐  │   │
│  │  │  Squid Proxy Container     │  │   │
│  │  │  - Domain ACL filtering    │  │   │
│  │  │  - HTTP/HTTPS proxy        │  │   │
│  │  └────────────────────────────┘  │   │
│  │           ▲                       │   │
│  │  ┌────────┼───────────────────┐  │   │
│  │  │ Agent Container            │  │   │
│  │  │ - Full filesystem access   │  │   │
│  │  │ - iptables redirect        │  │   │
│  │  │ - All traffic → Squid      │  │   │
│  │  └────────────────────────────┘  │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘

Key Containers

awf-squid - Squid proxy container (IP: 172.30.0.10)
- Filters HTTP/HTTPS traffic based on domain allowlist
- Logs all traffic decisions
awf-agent - Agent execution container (IP: 172.30.0.20)
- Runs the actual command/agent
- Has iptables rules to redirect traffic to Squid
- Full filesystem access via /host mount

Traffic Flow

Command runs in agent container
All HTTP/HTTPS traffic → iptables DNAT → Squid proxy
Squid checks domain against allowlist
Allowed → forward to destination
Blocked → return 403 Forbidden

Squid Log Analysis

# View Squid access log (shows traffic decisions)
docker exec awf-squid cat /var/log/squid/access.log
 
# Find blocked domains
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort -u
 
# Count blocked by domain
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort | uniq -c | sort -rn
 
# Real-time blocked traffic
docker exec awf-squid tail -f /var/log/squid/access.log | grep --line-buffered TCP_DENIED

Squid Decision Codes

TCP_TUNNEL:HIER_DIRECT = ALLOWED (HTTPS)
TCP_MISS:HIER_DIRECT = ALLOWED (HTTP)
TCP_DENIED:HIER_NONE = BLOCKED

Running Commands Through Firewall

# Basic usage
sudo awf --allow-domains github.com 'curl https://api.github.com'
 
# With debug logging
sudo awf --allow-domains github.com --log-level debug 'your-command'
 
# Keep containers for inspection
sudo awf --allow-domains github.com --keep-containers 'your-command'

Preserved Logs Locations

With --keep-containers:

Squid: /tmp/awf-<timestamp>/squid-logs/access.log
Agent: /tmp/awf-<timestamp>/agent-logs/

Normal execution (after cleanup):

Squid: /tmp/squid-logs-<timestamp>/access.log
Agent: /tmp/awf-agent-logs-<timestamp>/

# Find preserved logs
ls -ldt /tmp/awf-* /tmp/squid-logs-* 2>/dev/null | head -5
 
# View preserved Squid logs
sudo cat $(ls -t /tmp/squid-logs-*/access.log 2>/dev/null | head -1)

Debugging Workflow Failures

Step-by-Step Process

Identify the failing workflow run
```
gh run list --status failure --limit 5
```
Get run details
```
gh run view <run-id> --verbose
```

Download logs

gh run download <run-id> --dir ./logs
# Or use the script:
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --run-id <run-id>

Analyze the failure
- Check job logs for error messages
- Look for timeout issues
- Check for permission errors
- Review network-related errors
For agentic workflows, audit the run
```
gh aw audit <run-id> --json
```

If firewall-related, check Squid logs

# If containers are still running
docker exec awf-squid cat /var/log/squid/access.log
 
# Or check preserved logs
sudo cat /tmp/squid-logs-*/access.log

Common Failure Patterns

Permission Denied

Error: Resource not accessible by integration

Fix: Check permissions: in workflow frontmatter

Domain Blocked

curl: (56) Recv failure: Connection reset by peer

Fix: Add domain to --allow-domains or network: configuration

Timeout

Error: The operation was canceled.

Fix: Increase timeout-minutes in workflow configuration

Missing Tool

Tool 'xyz' not found

Fix: Add tool to tools: configuration in workflow frontmatter

Architecture - System architecture details
Troubleshooting - Common issues and solutions
GitHub Actions Integration - CI/CD setup
Logging Documentation - Comprehensive logging guide
Debug Firewall Skill - Firewall-specific debugging

npx skills add github/gh-aw-firewall --skill debugging-workflows

Documentation

SKILL.md

Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.

npx skills add github/gh-aw-firewall --skill debugging-workflows

Documentation

SKILL.mdView source

Debugging Workflows Skill

Use this skill when you need to debug GitHub Actions workflows, download workflow logs or summaries, or understand how agentic workflows and the AWF firewall work together.

Quick Start

Download Workflow Logs

Use the download-workflow-logs.ts script to download logs from a workflow run:

# Download logs from the latest workflow run
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts
 
# Download logs from a specific run ID
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --run-id 1234567890
 
# Download logs from a specific workflow
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --workflow test-integration.yml
 
# Save logs to a specific directory
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --output ./my-logs

Download Workflow Summary

Use the download-workflow-summary.ts script to get a summary of workflow runs:

# Get summary of latest workflow runs
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts
 
# Get summary for a specific workflow run
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --run-id 1234567890
 
# Get summary for a specific workflow file
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --workflow test-integration.yml
 
# Get summary as JSON
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --format json

GitHub CLI Commands

The gh CLI is essential for debugging workflows. Here are the most useful commands:

List Workflow Runs

# List recent workflow runs
gh run list --limit 10
 
# List runs for a specific workflow
gh run list --workflow test-integration.yml --limit 10
 
# List only failed runs
gh run list --status failure --limit 10
 
# List runs in JSON format for parsing
gh run list --json databaseId,name,status,conclusion,createdAt --limit 10

View Workflow Run Details

# View a specific run
gh run view <run-id>
 
# View run with job details
gh run view <run-id> --verbose
 
# View run as JSON
gh run view <run-id> --json jobs,conclusion,status

Download Run Logs

# Download all logs for a run
gh run download <run-id>
 
# Download specific artifact
gh run download <run-id> --name <artifact-name>
 
# Download to specific directory
gh run download <run-id> --dir ./logs

Watch a Running Workflow

# Watch a workflow run in real-time
gh run watch <run-id>
 
# Watch with exit code (useful for CI)
gh run watch <run-id> --exit-status

Re-run Failed Jobs

# Re-run failed jobs only
gh run rerun <run-id> --failed
 
# Re-run all jobs
gh run rerun <run-id>

Understanding Agentic Workflows

What are Agentic Workflows?

Key Components

Workflow File Format: .github/workflows/<name>.md
- YAML frontmatter for configuration
- Markdown body for AI instructions
- Compiles to .github/workflows/<name>.lock.yml
Triggers (on: field):
- Standard GitHub events: issues, pull_request, push, schedule
- Command triggers: /mention in issues/comments
- workflow_dispatch for manual triggers
Safe Outputs: Controlled way for AI to create GitHub entities
- create-issue: - Create GitHub issues
- create-pull-request: - Create PRs with git patches
- add-comment: - Add comments to issues/PRs
- add-labels: - Add labels to issues/PRs
- create-discussion: - Create GitHub discussions
Tools Configuration (tools: field):
- github: - GitHub API tools
- agentic-workflows: - Workflow introspection tools
- edit: - File editing tools
- web-fetch: / web-search: - Web access tools
- bash: - Shell command tools

Compiling Workflows

# Compile all workflows
gh aw compile
 
# Compile a specific workflow
gh aw compile <workflow-name>
 
# Compile with strict security checks
gh aw compile --strict

Debugging Agentic Workflows

# View status of all agentic workflows
gh aw status
 
# Download and analyze logs from previous runs
gh aw logs <workflow-name> --json
 
# Audit a specific run for issues
gh aw audit <run-id> --json

Common Issues

Missing Tool Calls: Check missing_tools in audit output
Safe Output Failures: Review safe_outputs.jsonl artifact
Permission Issues: Verify permissions: block in frontmatter
Network Blocked: Check network: configuration for allowed domains

Understanding the AWF Firewall

What is AWF?

Architecture Overview

┌─────────────────────────────────────────┐
│  Host (GitHub Actions Runner / Local)   │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │   Firewall CLI (awf)              │ │
│  │   - Parse arguments                │ │
│  │   - Generate Squid config          │ │
│  │   - Start Docker Compose           │ │
│  └────────────────────────────────────┘ │
│           │                              │
│           ▼                              │
│  ┌──────────────────────────────────┐   │
│  │   Docker Compose                 │   │
│  │  ┌────────────────────────────┐  │   │
│  │  │  Squid Proxy Container     │  │   │
│  │  │  - Domain ACL filtering    │  │   │
│  │  │  - HTTP/HTTPS proxy        │  │   │
│  │  └────────────────────────────┘  │   │
│  │           ▲                       │   │
│  │  ┌────────┼───────────────────┐  │   │
│  │  │ Agent Container            │  │   │
│  │  │ - Full filesystem access   │  │   │
│  │  │ - iptables redirect        │  │   │
│  │  │ - All traffic → Squid      │  │   │
│  │  └────────────────────────────┘  │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘

Key Containers

awf-squid - Squid proxy container (IP: 172.30.0.10)
- Filters HTTP/HTTPS traffic based on domain allowlist
- Logs all traffic decisions
awf-agent - Agent execution container (IP: 172.30.0.20)
- Runs the actual command/agent
- Has iptables rules to redirect traffic to Squid
- Full filesystem access via /host mount

Traffic Flow

Command runs in agent container
All HTTP/HTTPS traffic → iptables DNAT → Squid proxy
Squid checks domain against allowlist
Allowed → forward to destination
Blocked → return 403 Forbidden

Squid Log Analysis

# View Squid access log (shows traffic decisions)
docker exec awf-squid cat /var/log/squid/access.log
 
# Find blocked domains
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort -u
 
# Count blocked by domain
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort | uniq -c | sort -rn
 
# Real-time blocked traffic
docker exec awf-squid tail -f /var/log/squid/access.log | grep --line-buffered TCP_DENIED

Squid Decision Codes

TCP_TUNNEL:HIER_DIRECT = ALLOWED (HTTPS)
TCP_MISS:HIER_DIRECT = ALLOWED (HTTP)
TCP_DENIED:HIER_NONE = BLOCKED

Running Commands Through Firewall

# Basic usage
sudo awf --allow-domains github.com 'curl https://api.github.com'
 
# With debug logging
sudo awf --allow-domains github.com --log-level debug 'your-command'
 
# Keep containers for inspection
sudo awf --allow-domains github.com --keep-containers 'your-command'

Preserved Logs Locations

With --keep-containers:

Squid: /tmp/awf-<timestamp>/squid-logs/access.log
Agent: /tmp/awf-<timestamp>/agent-logs/

Normal execution (after cleanup):

Squid: /tmp/squid-logs-<timestamp>/access.log
Agent: /tmp/awf-agent-logs-<timestamp>/

# Find preserved logs
ls -ldt /tmp/awf-* /tmp/squid-logs-* 2>/dev/null | head -5
 
# View preserved Squid logs
sudo cat $(ls -t /tmp/squid-logs-*/access.log 2>/dev/null | head -1)

Debugging Workflow Failures

Step-by-Step Process

Identify the failing workflow run
```
gh run list --status failure --limit 5
```
Get run details
```
gh run view <run-id> --verbose
```

Download logs

gh run download <run-id> --dir ./logs
# Or use the script:
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --run-id <run-id>

Analyze the failure
- Check job logs for error messages
- Look for timeout issues
- Check for permission errors
- Review network-related errors
For agentic workflows, audit the run
```
gh aw audit <run-id> --json
```

If firewall-related, check Squid logs

# If containers are still running
docker exec awf-squid cat /var/log/squid/access.log
 
# Or check preserved logs
sudo cat /tmp/squid-logs-*/access.log

Common Failure Patterns

Permission Denied

Error: Resource not accessible by integration

Fix: Check permissions: in workflow frontmatter

Domain Blocked

curl: (56) Recv failure: Connection reset by peer

Fix: Add domain to --allow-domains or network: configuration

Timeout

Error: The operation was canceled.

Fix: Increase timeout-minutes in workflow configuration

Missing Tool

Tool 'xyz' not found

Fix: Add tool to tools: configuration in workflow frontmatter

Architecture - System architecture details
Troubleshooting - Common issues and solutions
GitHub Actions Integration - CI/CD setup
Logging Documentation - Comprehensive logging guide
Debug Firewall Skill - Firewall-specific debugging

debugging-workflows

Documentation

Documentation

debugging-workflows

Documentation

Debugging Workflows Skill

Quick Start

Download Workflow Logs

Download Workflow Summary

GitHub CLI Commands

List Workflow Runs

View Workflow Run Details

Download Run Logs

Watch a Running Workflow

Re-run Failed Jobs

Understanding Agentic Workflows

What are Agentic Workflows?

Key Components

Compiling Workflows

Debugging Agentic Workflows

Common Issues

Understanding the AWF Firewall

What is AWF?

Architecture Overview

Key Containers

Traffic Flow

Squid Log Analysis

Squid Decision Codes

Running Commands Through Firewall

Preserved Logs Locations

Debugging Workflow Failures

Step-by-Step Process

Common Failure Patterns

Permission Denied

Domain Blocked

Timeout

Missing Tool

Related Documentation

Documentation

Documentation

Debugging Workflows Skill

Quick Start

Download Workflow Logs

Download Workflow Summary

GitHub CLI Commands

List Workflow Runs

View Workflow Run Details

Download Run Logs

Watch a Running Workflow

Re-run Failed Jobs

Understanding Agentic Workflows

What are Agentic Workflows?

Key Components

Compiling Workflows

Debugging Agentic Workflows

Common Issues

Understanding the AWF Firewall

What is AWF?

Architecture Overview

Key Containers

Traffic Flow

Squid Log Analysis

Squid Decision Codes

Running Commands Through Firewall

Preserved Logs Locations

Debugging Workflow Failures

Step-by-Step Process

Common Failure Patterns

Permission Denied

Domain Blocked

Timeout

Missing Tool

Related Documentation