github-actions-silent-failures

GitHub Actions silent-failure diagnostics

Three unrelated GitHub Actions failure classes that share one property: none of them produce a red check where you'd expect to look. A required gate can go dark for months with nobody noticing, because there's nothing red to see.

Runs that fail with zero jobs (startup_failure)

A caller workflow can fail at run creation, before any job exists. The run shows startup_failure, an empty jobs list, and no logs — nothing failed, because nothing ran. In the worst recorded case a repository's CI gate startup-failed on every run for five months (~420 runs): no lint, schema, or content check executed in that window, and merges proceeded on a separate gate alone.

The API will not tell you why. gh run view and the REST/GraphQL APIs report only startup_failure and a generic "workflow file issue" — the real error text exists only on the run's HTML page. Any triage that stops at gh run view concludes "no useful information" and moves on, which is how this stays undiagnosed. Don't pull the whole rendered page into context — fetch it and grep for the annotation banner (grep -A5 'annotation-message\|workflow-file-issue') to pull out just the error line, or check the run's referenced_workflows field first (see Detection below) since it often narrows this to one permissions mismatch without a page fetch at all.

Four distinct causes produce this exact symptom:

1. A nested job's permissions exceed the caller's grant. GitHub validates every nested job of every referenced reusable workflow against the calling job's permission grant at run-creation time — including jobs whose if: condition would have skipped them. One mismatch fails the entire caller run. Fix by either granting the needed permission at the call-site job, or dropping an unused permission from the nested job.
2. permissions: {} at workflow level on a cross-repo workflow_call. An empty permissions block means the token gets zero grants. Empty is not the same as default, and this startup-fails instantly.
3. A type: number workflow_call input receiving a string. A caller passing "659" to a number-typed input startup-fails silently. Prefer type: string consistently on workflow_call inputs — the value gets interpolated as text anyway.
4. Two jobs in one workflow calling the same reusable workflow. The second job silently disappears — no error, no YAML complaint, just absent from the run. This is the one variant that does not report startup_failure; it quietly does less than the file says.