Debugging Workflows | GitHub Agentic Workflows
Skip to main content 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. All agent entry points use the same debugging bootstrap and inventory and shared debugging strategy . Start with existing evidence; diagnosis does not authorize dispatch. The shared strategy owns local execution, MCP startup review, compilation, and live-test authorization.
For enterprise host configuration, retain the GHE-specific guide . Debugging with the Copilot CLI Section titled “Debugging with the Copilot CLI” Use this section only when choosing a new local Copilot assistant session. Otherwise continue with your existing agent and available evidence tools. Launch copilot and invoke agentic-workflows to load the debugging instructions. Skills do not grant tool access; CLI/MCP capabilities depend on the client configuration and authorization.
Then paste the failing run URL: Debug this workflow run: https://github.com/OWNER/REPO/actions/runs/RUN_ID With authorized access, Copilot can analyze existing logs and suggest a cause or fix. Cached/redacted evidence also works. Publication requires the user’s scope and repository rules; a debugging request does not automatically open a PR. Alternative entry points Section titled “Alternative entry points” Copilot Chat on GitHub.com : in repositories configured for agentic authoring , use agentic-workflows debug <run-url> .
Any coding agent : paste this prompt to use available tools or cached evidence without mandatory installation: 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 Section titled “Debugging with CLI Commands” Use a matching target checkout; otherwise pass --repo OWNER/REPO for this github.com guide.
Never substitute an unrelated checkout for the supplied target. Auditing a Specific Run Section titled “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.
Terminal window gh aw audit https://github.com/OWNER/REPO/actions/runs/12345678 --no-baseline --timeout 2m gh aw audit https://github.com/OWNER/REPO/actions/runs/123/job/456#step:7:1 gh aw audit 12345678 --repo OWNER/REPO --parse # parse to markdown gh aw audit 12345678 12345679 --repo OWNER/REPO # compare two runs gh aw audit 12345678 12345679 --repo OWNER/REPO --group --json # recurrence findings For security and performance trends across multiple runs, use gh aw logs --format : Terminal window gh aw logs my-workflow --format markdown --count 10 gh aw logs my-workflow --format markdown --last 5 --json See Audit Commands for complete flag documentation.
Analyzing Workflow Logs Section titled “Analyzing Workflow Logs” gh aw logs downloads and analyzes logs across multiple runs (tool usage, network patterns, errors). Results are cached for 10–100× speedup on later runs. Terminal window gh aw logs my-workflow gh aw logs my-workflow -c 10 --start-date -1w # filter by count and date gh aw logs my-workflow --firewall # include firewall analysis gh aw logs my-workflow --safe-output # include safe-output details gh aw logs my-workflow --json # JSON for scripting Logs reports group failed, timed-out, cancelled, and startup-failure runs into failure investigation clusters using failed jobs/steps, MCP failures, missing tools/data, and blocked domains from the downloaded metadata.
Clusters describe shared symptoms, not proven root causes, and can overlap, so do not sum their counts into a failure rate. Intentional failures and different failure kinds stay separate. Start with [failure_investigation] : unique failure/evidence counts and a deduplicated plan of up to five runs. Selection prioritizes specific failure boundaries, then maximizes new cluster coverage and affected-run reach, preferring richer/newer diagnostics on ties.
Generic failure-handler aftermath ranks last, and intentional failures are excluded. Remaining cluster counts show the plan is not exhaustive. The default [failure_clusters] output is a compact overview with representative IDs. Use -v for text membership, or project failure_investigation from --json . JSON and summary files keep full failure_clusters , per-run failure_cluster_ids , typed signal.job / signal.step , repository/workflow/engine/model facets, and first/last-seen timestamps.
Up to three representatives per cluster prefer distinct contexts and include cached audit_path / logs_path ; read cached evidence before another audit. Stable cluster IDs identify the same symptom across queries; membership reflects only the returned runs. No extra downloads or model calls are needed. Without detailed evidence (including older cache records without signals), a metadata_only cluster groups runs in the same workflow and repository without asserting a shared cause.
Each cluster’s statistics exposes its failed_population , observed share , and Wilson 95% bounds ( wilson_lower_95 / wilson_upper_95 ). The denominator includes unique returned failures, including metadata-only runs; intentional failures form a separate population. These are symptom shares, not workflow failure rates. Correlated retries, incomplete collection, and missing diagnostics limit interpretation, so do not use them as causal confidence, a significance test, or a forecast.
Checking Workflow Health Section titled “Checking Workflow Health” gh aw health reports workflow status across all workflows in a repository. It walks backward independently for each active AW until it has five completed, first-attempt runs for the current revision, encounters a revision boundary, or exhausts the maximum horizon ( --days 7 , 30 , or 90 ; default 7 ). Rates, trends, durations, and token averages describe the recent current-revision sample, not the entire period.
Sparse workflows and workflows with no recent runs remain visible as insufficient evidence. Revision identity uses frontmatter_hash , body_hash , and compiler version from gh-aw-metadata at each run’s immutable commit, not repository SHA changes alone. A branch-head metadata check detects pushed revisions with no runs yet. JSON workflows[].revisions (or revisions for one workflow) separates branch/event cohorts and includes current/previous hashes, counts, and run IDs. recovery_observed requires five successful first-attempt runs after a changed revision whose sampled predecessor failed and finished before those runs began.
This is observed recovery, not proof that a particular commit fixed the cause. Missing hashes and triggers whose head SHA does not identify the executing workflow, including workflow_run and pull_request , remain revision_unknown . failure_clusters and failure_investigation describe current-revision failures using the same implementation as logs ; historical failures remain in revision comparisons, not the current audit plan.
Health reuses fresh summaries from .github/aw/logs (override with --logs-dir PATH ) without downloading artifacts. Missing or stale summaries produce metadata_only clusters. Cluster shares are not workflow failure rates. Health checks the target host’s core API quota, reuses immutable revision lookups, and stops rather than sleeping or retrying on primary or secondary rate limits. collection records quota, request counts, and partial results.
Collection is bounded to 1,000 data requests and 20 pages per workflow; quota, request, or pagination limits are explicit. Incomplete evidence never counts as healthy. Use logs for a wider historical population and audit for targeted comparisons. Inspecting MCP Configuration Section titled “Inspecti
The rest of this page is on the live site.