Debugging Workflows

This guide shows you how to debug agentic workflow failures on github.com using the Copilot CLI, the gh aw debugging commands, and manual investigation techniques.

Tip

The fastest path to a fix is to let an AI agent debug it for you. Launch the Copilot CLI, invoke the agentic-workflows skill, and paste the failing run URL.

Debugging with the Copilot CLI

The Copilot CLI is the recommended first step: it audits logs, traces failures, and suggests fixes interactively.

Launch copilot, invoke agentic-workflows to enable gh aw audit, gh aw logs, and related debugging tools. Then paste the failing run URL:

Debug this workflow run: https://github.com/OWNER/REPO/actions/runs/RUN_ID

Copilot downloads the logs, identifies the root cause (missing tools, permission errors, network blocks), and suggests fixes or opens a PR. Follow-up questions like “What domains were blocked?” or “Why did the MCP server fail?” work too.

Alternative entry points

• Copilot Chat on GitHub.com (requires agentic authoring setup): agentic-workflows debug <run-url>

• Any coding agent: paste this prompt to install gh aw and run the standalone analysis:

  Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md
  
  The failed workflow run is at https://github.com/OWNER/REPO/actions/runs/RUN_ID

Debugging with CLI Commands

Auditing a Specific Run

gh aw audit breaks down a single run — failure analysis and root cause, behavior fingerprint (network/tool/cost profile), tool usage, MCP server status, firewall analysis, token/cost metrics, and safe-outputs. Accepts a run ID, run URL, job URL (extracts first failing step), or step URL.

gh aw audit 12345678