npx skills add ...
npx skills add github/gh-aw-firewall --skill debugging-workflows
npx skills add github/gh-aw-firewall --skill debugging-workflows
Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.
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.
Use the download-workflow-logs.ts script to download logs from a workflow run:
Use the download-workflow-summary.ts script to get a summary of workflow runs:
The gh CLI is essential for debugging workflows. Here are the most useful commands:
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).
Workflow File Format: .github/workflows/<name>.md
.github/workflows/<name>.lock.ymlTriggers (on: field):
issues, pull_request, push, schedule/mention in issues/commentsworkflow_dispatch for manual triggersSafe Outputs: Controlled way for AI to create GitHub entities
create-issue: - Create GitHub issuescreate-pull-request: - Create PRs with git patchesadd-comment: - Add comments to issues/PRsadd-labels: - Add labels to issues/PRscreate-discussion: - Create GitHub discussionsTools Configuration (tools: field):
github: - GitHub API toolsagentic-workflows: - Workflow introspection toolsedit: - File editing toolsweb-fetch: / web-search: - Web access toolsbash: - Shell command toolsmissing_tools in audit outputsafe_outputs.jsonl artifactpermissions: block in frontmatternetwork: configuration for allowed domainsAWF (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.
awf-squid - Squid proxy container (IP: 172.30.0.10)
awf-agent - Agent execution container (IP: 172.30.0.20)
/host mountTCP_TUNNEL:HIER_DIRECT = ALLOWED (HTTPS)TCP_MISS:HIER_DIRECT = ALLOWED (HTTP)TCP_DENIED:HIER_NONE = BLOCKEDWith --keep-containers:
/tmp/awf-<timestamp>/squid-logs/access.log/tmp/awf-<timestamp>/agent-logs/Normal execution (after cleanup):
/tmp/squid-logs-<timestamp>/access.log/tmp/awf-agent-logs-<timestamp>/Identify the failing workflow run
Get run details
Download logs
Analyze the failure
For agentic workflows, audit the run
If firewall-related, check Squid logs
Fix: Check permissions: in workflow frontmatter
Fix: Add domain to --allow-domains or network: configuration
Fix: Increase timeout-minutes in workflow configuration
Fix: Add tool to tools: configuration in workflow frontmatter
# 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# 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 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 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 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 only
gh run rerun <run-id> --failed
# Re-run all jobs
gh run rerun <run-id># Compile all workflows
gh aw compile
# Compile a specific workflow
gh aw compile <workflow-name>
# Compile with strict security checks
gh aw compile --strict# 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┌─────────────────────────────────────────┐
│ 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 │ │ │
│ │ └────────────────────────────┘ │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────┘# 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# 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'# 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)