鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

debugging-workflows

提供 GitHub 智能工作流的端到端诊断能力,支持批量下载与结构化解析运行日志、深度审计单次执行过程、识别工具缺失与权限不足等典型故障,并结合工作流编译、MCP 配置检查及防火墙日志分析实现精准排障。

效率工具商业与营销开发运维
访问 GitHub
文档Skills.MD
name
debugging-workflows
description
Guide for debugging GitHub Agentic Workflows - analyzing logs, auditing runs, and troubleshooting issues

Debugging GitHub Agentic Workflows

This skill provides comprehensive guidance for debugging GitHub Agentic Workflows, including scripts to download and analyze workflow logs, audit specific runs, and understand how agentic workflows operate.

Table of Contents

  • Quick Start
  • Downloading Workflow Logs
  • Auditing Specific Runs
  • How Agentic Workflows Work
  • Common Issues and Solutions
  • Advanced Debugging Techniques
  • Reference Commands

Quick Start

Download Logs from Recent Runs

▼
bash
复制代码
# 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 a Specific Run

▼
bash
复制代码
# 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

Downloading Workflow Logs

The gh aw logs command downloads workflow run artifacts and logs from GitHub Actions for analysis.

Basic Usage

▼
bash
复制代码
# 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 Options

▼
bash
复制代码
# 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

Output Options

▼
bash
复制代码
# 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

Downloaded Artifacts

When you run gh aw logs, the following artifacts are downloaded for each run:

FileDescription
aw_info.jsonEngine configuration and workflow metadata
safe_output.jsonlAgent's final output content (when non-empty)
agent_output/Agent logs directory
agent-stdio.logAgent standard output/error logs
aw.patchGit patch of changes made during execution
workflow-logs/GitHub Actions job logs (organized by job)
summary.jsonComplete metrics and run data for all runs

Example: Analyze Recent Failures

▼
bash
复制代码
# 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")'

Auditing Specific Runs

The gh aw audit command investigates a single workflow run in detail, downloading artifacts, detecting errors, and generating a report.

Basic Usage

▼
bash
复制代码
# 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

Output Options

▼
bash
复制代码
# 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

Audit Report Contents

The audit command provides:

  • Error Detection: Errors and warnings from workflow logs
  • MCP Tool Usage: Statistics on tool calls by the AI agent
  • Missing Tools: Tools the agent tried to use but weren't available
  • Execution Metrics: Duration, token usage, and cost information
  • Safe Output Analysis: What GitHub operations were attempted

Example: Investigate a Failed Run

▼
bash
复制代码
# 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 }'

How Agentic Workflows Work

Understanding the workflow architecture helps in debugging.

Workflow Structure

Agentic workflows use a markdown + YAML frontmatter format:

▼
markdown
复制代码
--- 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 }}.

Execution Flow

▼
text
复制代码
1. Trigger Event (issue opened, PR created, schedule, etc.) ↓ 2. Activation Job - Validates permissions - Processes safe-inputs - 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

Key Components

ComponentPurposeConfiguration
EngineAI model to useengine: copilot, claude, codex
ToolsAPIs available to agenttools: section with MCP servers
Safe-InputsContext passed to agentsafe-inputs: with GitHub expressions
Safe-OutputsResources agent can createsafe-outputs: with allowed operations
PermissionsGitHub token permissionspermissions: block
NetworkAllowed network accessnetwork: with domain/ecosystem lists

Compilation Process

▼
bash
复制代码
# 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.

Common Issues and Solutions

Missing Tool Errors

Symptoms:

  • Error: "Tool 'github:read_issue' not found"
  • Agent cannot access GitHub APIs

Solution: Add GitHub MCP server configuration:

▼
yaml
复制代码
tools: github: mode: remote toolsets: [default]

Permission Errors

Symptoms:

  • HTTP 403 (Forbidden) errors
  • "Resource not accessible" errors

Solution: Add required permissions:

▼
yaml
复制代码
permissions: contents: read issues: write pull-requests: write

Safe-Input Errors

Symptoms:

  • "missing tool configuration for safeinputs-gh"
  • Environment variable not available

Solution: Configure safe-inputs:

▼
yaml
复制代码
safe-inputs: issue: title: ${{ github.event.issue.title }} body: ${{ github.event.issue.body }}

Safe-Output Errors

Symptoms:

  • Agent tries to create resources but fails
  • "Safe output not enabled" errors

Solution: Enable safe-outputs:

▼
yaml
复制代码
safe-outputs: staged: false # Set to false to actually create resources create-issue: labels: [ai-generated]

Network Access Errors

Symptoms:

  • Firewall denials
  • URLs appearing as "(redacted)"

Solution: Configure network access:

▼
yaml
复制代码
network: allowed: - defaults - python # For PyPI - node # For npm - "api.example.com" # Custom domains

Timeout Errors

Symptoms:

  • Workflow exceeds time limit
  • Agent loops or hangs

Solution: Increase timeout or optimize prompt:

▼
yaml
复制代码
timeout-minutes: 30 # Increase from default

Advanced Debugging Techniques

Polling In-Progress Runs

When a run is still executing:

▼
bash
复制代码
# 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

Inspecting MCP Configuration

▼
bash
复制代码
# Inspect MCP servers for a workflow gh aw mcp inspect <workflow-name> # List all workflows with MCP servers gh aw mcp list

Checking Workflow Status

▼
bash
复制代码
# Show status of all agentic workflows gh aw status

Downloading Specific Artifacts

▼
bash
复制代码
# Download only the agent log artifact GH_REPO=owner/repo gh run download <run-id> -n agent-stdio.log

Inspecting Job Logs

▼
bash
复制代码
# View specific job logs gh run view <run-id> gh run view --job <job-id> --log

Analyzing Firewall Logs

▼
bash
复制代码
# Parse firewall logs for network issues gh aw logs --parse # Check firewall-enabled runs gh aw logs --firewall

Debug Mode Compilation

▼
bash
复制代码
# 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

Reference Commands

Log Analysis Commands

CommandDescription
gh aw logsDownload logs for all workflows
gh aw logs <workflow>Download logs for specific workflow
gh aw logs --jsonOutput as JSON
gh aw logs --start-date -1dFilter by date
gh aw logs --engine copilotFilter by engine
gh aw logs --parseGenerate Markdown reports

Audit Commands

CommandDescription
gh aw audit <run-id>Audit specific run
gh aw audit <url>Audit from GitHub URL
gh aw audit <run-id> --jsonOutput as JSON
gh aw audit <run-id> --parseParse logs to Markdown

MCP Commands

CommandDescription
gh aw mcp listList workflows with MCP servers
gh aw mcp inspect <workflow>Inspect MCP configuration

Status Commands

CommandDescription
gh aw statusShow all workflow status
gh aw compileCompile all workflows
gh aw compile <workflow>Compile specific workflow
gh aw compile --strictCompile with security checks

Workflow Execution Commands

CommandDescription
gh aw run <workflow>Trigger workflow manually
gh workflow run <name>.lock.ymlAlternative trigger method
gh run watch <run-id>Monitor running workflow

Additional Resources

  • Workflow Health Monitoring Runbook - Step-by-step investigation procedures
  • Common Issues Reference - Frequently encountered issues
  • Error Reference - Error codes and solutions
  • GitHub MCP Server Documentation - Tool configuration reference
效率工具
商业与营销
开发运维

快捷安装

复制到终端去安装 Skill

npxskillsaddgithubnext/gh-aw--skill"debugging-workflows"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
Skills 推荐
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
load-balancer-configurator
根据用户需求自动生成各类负载均衡器的生产级配置,覆盖 ALB、NLB、Nginx 和 HAProxy 等主流类型,适配不同协议、端口、健康检查及后端服务拓扑,支持直接集成到基础设施即代码流程中。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
definition-of-done-generator
自动生成项目完成标准的规范定义与配置文件,提供符合企业级工作流要求的最佳实践指导,输出可直接投入生产环境的代码和验证结果,适用于需要标准化流程审批、合规审查及跨系统集成的复杂项目管理场景。
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI