---
name: debug-workflow
description: Guide for investigating GitHub Actions workflow failures in auto-deploy or app-delivery. Covers fetching run logs, reading local source code, and triaging common failure modes (transient, infra, config, app-delivery, code bug). The agent never retries, reruns, or modifies anything — it only diagnoses and reports findings.
---

# Debug a Workflow Failure

Use this guide when a workflow run has failed or an operator asks you to investigate
a GitHub Actions failure in any repository or environment.

## Step 1 — Get the run logs

If you have a run ID, download the logs directly:

```python
result = await get_workflow_run_logs(run_id=<run_id>, repo="<owner/repo>")
# result["path"] is the local log file; result["size_bytes"] tells you how large it is
content = await read_file(result["path"])
```

If you only have an issue number, read the issue comments to find the triggered run ID:

```python
body = await get_issue_body(issue_number=<issue_number>)
comments = await list_issue_comments(issue_number=<issue_number>)
# look for <!-- autopilot:triggered run_id=NNN --> markers
```

If you don't have a run ID at all, list recent runs and filter by workflow or status:

```python
runs = await list_workflow_runs(
    repo="<owner/repo>",
    workflow="deploy-aws-premium-region.yml",  # omit to list all workflows
    status="failure",                          # omit to list all statuses
    limit=10,
)
# each entry: {"run_id", "name", "workflow", "branch", "status", "conclusion", "createdAt", "url"}
```

You can also check current run status:

```python
status = await get_workflow_run_status(run_id=<run_id>, repo="<owner/repo>")
# returns "running" or a conclusion string: success | failure | cancelled | timed_out
```

## Step 2 — Read the workflow definition

Understand what the workflow does before triaging errors:

```python
files = await glob("**/*.yml", root_dir="<auto_deploy_dir>/.github/workflows")
content = await read_file("<auto_deploy_dir>/.github/workflows/deploy-aws-premium-region.yml")
```

Key locations:
- `<auto_deploy_dir>/.github/workflows/` — region deploy/destroy workflows
- `<app_delivery_dir>/.github/workflows/` — app-delivery delivery workflows

## Step 3 — Triage the failure

### Transient / infrastructure failures
Symptoms: network timeouts, rate limits, API errors unrelated to the workflow code.

Action: **Report only** — document the failure clearly (error message, affected step,
timestamp). Do not retry or rerun the workflow. Set `conclusion="action_required"` so
the operator can decide whether to re-trigger manually.

### Configuration / parameter errors
Symptoms: workflow step fails with a "not found", "invalid", or "permission denied" error
that traces back to an incorrect input value.

Action: **Report only** — document which parameter is incorrect and what the expected
value or format should be. Set `conclusion="action_required"`.

### App-delivery failures
After a deploy workflow completes, app-delivery may fail independently:

```python
failures = await list_workflow_runs(
    repo="tidbcloud/app-delivery",
    status="failure",
    limit=20,
)
```

For each matching failure, fetch the logs:

```python
result = await get_workflow_run_logs(run_id=<ad_run_id>, repo="tidbcloud/app-delivery")
content = await read_file(result["path"])
```

Common patterns:
- **Merge conflict** — identify the conflicting automated PR (list open PRs with `list_prs`),
  include the PR URL in your diagnosis report, set `conclusion="action_required"`.
  Do not close the PR or rerun the workflow.
- **Already deployed** — idempotent, report success
- **Unrelated failure** — report to operator

### Code bug
Symptoms: a Python exception in autopilot source, or a logic/configuration bug in
auto-deploy or app-delivery source code.

Action: **Report only** — read the relevant source files to confirm the bug, then
include a **Suggested fix** section in the diagnosis report describing:
- The file path and relevant line numbers
- What is wrong
- The recommended code change

Do not modify any files or open a pull request. Set `conclusion="action_required"`.

### Missing capability or skill

Symptoms: the workflow failure (or the operator's request) reveals an automation gap —
autopilot lacks a tool, capability, or skill script needed to handle a class of situation.

Action: **Report only** — describe what gap was found and what would be needed to
address it. Set `conclusion="action_required"` so the operator can decide whether to
extend autopilot.

## Step 4 — Report your findings

Always summarise:
- What failed and in which step
- Root cause (transient, config, code bug, infra, merge conflict, missing capability)
- Evidence (relevant log excerpt or error message)
- Suggested fix (for code bugs: file, lines, recommended change)
- What the operator should do next