com um clique
debugging-workflows
// Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.
// Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.
| name | debugging-workflows |
| description | Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together. |
| allowed-tools | Bash(gh:*), Bash(curl:*), Bash(npx:*), Bash(node:*), Bash(cat:*), Bash(ls:*), Bash(grep:*), Bash(jq:*), Read |
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:
# 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
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
The gh CLI is essential for debugging workflows. Here are the most useful commands:
# 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>
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 tools# 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
missing_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.
┌─────────────────────────────────────────┐
│ 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 │ │ │
│ │ └────────────────────────────┘ │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────┘
awf-squid - Squid proxy container (IP: 172.30.0.10)
awf-agent - Agent execution container (IP: 172.30.0.20)
/host mount# 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
TCP_TUNNEL:HIER_DIRECT = ALLOWED (HTTPS)TCP_MISS:HIER_DIRECT = ALLOWED (HTTP)TCP_DENIED:HIER_NONE = BLOCKED# 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'
With --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>/# 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)
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
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
Error: Resource not accessible by integration
Fix: Check permissions: in workflow frontmatter
curl: (56) Recv failure: Connection reset by peer
Fix: Add domain to --allow-domains or network: configuration
Error: The operation was canceled.
Fix: Increase timeout-minutes in workflow configuration
Tool 'xyz' not found
Fix: Add tool to tools: configuration in workflow frontmatter
Use the AWF (Agentic Workflow Firewall) to run commands with network isolation and domain whitelisting. Provides L7 HTTP/HTTPS egress control for AI agents.
Regenerate and post-process all agentic workflows. Use when gh-aw is updated, workflow .md files change, or when asked to recompile/regenerate workflows.
Use the AWF (Agentic Workflow Firewall) to run commands with network isolation and domain whitelisting. Provides L7 HTTP/HTTPS egress control for AI agents.
Debug the AWF firewall by inspecting Docker containers (awf-squid, awf-agent), analyzing Squid access logs, checking iptables rules, and troubleshooting blocked domains or network issues.
Practical Python scripts for debugging awf - parse logs, diagnose issues, inspect containers, test domains