Investigate a GitHub Actions Failure
Use this skill when a GitHub Actions workflow fails, does not trigger, or behaves
unexpectedly.
Workflow
1. Locate the run
- Find the workflow runs for the branch/commit in question: the failing run, its
head SHA, and the workflow name.
- Confirm the run's event (push, pull_request, schedule, manual) — an unexpected
trigger is itself a clue.
2. Isolate the failure
- From the run, get the jobs and their conclusions.
- Find the first failed job and the failing step; fetch the step log.
- Read the log tail first (the actual error), then scan up for context.
3. Classify the failure
Common classes:
- Toolchain: dependency install/version drift, node/python/rust version
mismatch, cache issues. Look at the install/setup step.
- Test: assertion failures, flaky tests (timeouts, order dependence,
network-dependent tests). Check if the same test fails on main.
- Build: type errors, lint, bundling, missing env at build time.
- Infra: runner provisioning, secrets missing, registry/auth failures,
concurrency limits.
- Workflow YAML: invalid expression, missing permissions, matrix expansion
failure.
4. Correlate
- Compare against the last green run on the same branch: what changed in between
(commit range, dependency bumps, workflow file changes)?
- If the failure reproduces on main, it is not caused by the PR's code.
5. Report
State: the run/workflow/job/step, the decisive log lines, the root cause, and the
narrowest fix (pin a dependency, fix the test, adjust the workflow, add a
missing secret). Reruns/retries of the workflow are write actions — only
trigger them when the user asks.
1---2name: investigate-ci3description: Investigate GitHub Actions workflow failures: find the failed run, read the failing job step, examine logs, and identify the root cause. Use when a CI run fails, a workflow does not trigger, or a check is stuck or skipped.4---56# Investigate a GitHub Actions Failure78Use this skill when a GitHub Actions workflow fails, does not trigger, or behaves9unexpectedly.1011## Workflow1213### 1. Locate the run1415- Find the workflow runs for the branch/commit in question: the failing run, its16 head SHA, and the workflow name.17- Confirm the run's event (push, pull_request, schedule, manual) — an unexpected18 trigger is itself a clue.1920### 2. Isolate the failure2122- From the run, get the jobs and their conclusions.23- Find the first failed job and the failing step; fetch the step log.24- Read the log tail first (the actual error), then scan up for context.2526### 3. Classify the failure2728Common classes:2930- **Toolchain**: dependency install/version drift, node/python/rust version31 mismatch, cache issues. Look at the install/setup step.32- **Test**: assertion failures, flaky tests (timeouts, order dependence,33 network-dependent tests). Check if the same test fails on main.34- **Build**: type errors, lint, bundling, missing env at build time.35- **Infra**: runner provisioning, secrets missing, registry/auth failures,36 concurrency limits.37- **Workflow YAML**: invalid expression, missing permissions, matrix expansion38 failure.3940### 4. Correlate4142- Compare against the last green run on the same branch: what changed in between43 (commit range, dependency bumps, workflow file changes)?44- If the failure reproduces on main, it is not caused by the PR's code.4546### 5. Report4748State: the run/workflow/job/step, the decisive log lines, the root cause, and the49narrowest fix (pin a dependency, fix the test, adjust the workflow, add a50missing secret). Reruns/retries of the workflow are **write** actions — only51trigger them when the user asks.52
HiAi-gg