Expose the startup_failure reason via the REST/GraphQL API

[otakuu]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

API

Body

When a workflow run ends in conclusion: startup_failure - e.g. invalid workflow YAML, or a top-level permissions: block missing actions: read - the web UI shows a precise reason, for example:

Invalid workflow file: .github/workflows/build.yml#L13
You have an error in your yaml syntax - did not find expected key

But that reason is not available through any public API. I verified this against a real startup_failure run:

Endpoint	Result
GET /repos/{o}/{r}/actions/runs/{id}	only conclusion: startup_failure, no message/error field
GET /repos/{o}/{r}/actions/runs/{id}/jobs	total_count: 0
GET /repos/{o}/{r}/actions/runs/{id}/logs	404
GET /repos/{o}/{r}/check-suites/{id}/check-runs (incl. ?filter=all)	total_count: 0
GraphQL checkSuite.checkRuns	0

Because the workflow file never parsed, no job or check run is ever created - so there is nothing for the API to return. The reason clearly exists server-side (the UI renders it), it's just not surfaced anywhere callable.

Why this matters

We run a GitHub App that listens for check_suite completed events and posts a Slack alert on startup_failure. We can link the run, but we can't tell the team why it failed - which is the single most useful piece of information. Reading the workflow file ourselves can't reproduce GitHub's exact parser error.

Prior art

This was asked (@ohaval) in 2023 in https://github.com/orgs/community/discussions/57536 and left unanswered - the only workaround offered was scraping the run page HTML, which is brittle and doesn't work for private repositories.

Request

Surface the startup-failure reason via the API - for example an error/message field on the workflow run or check suite object, or an annotation reachable through the Checks API.

[Cyb4819]

I’ve hit this exact wall before and it’s incredibly frustrating. I spent way too long looking through the Actions, Checks, and Logs APIs assuming I was missing something, only to discover that the detailed error is only available in the UI. For 'startup_failure', the reason is usually the most important piece of information. Knowing that a workflow failed to start is helpful, but knowing why it failed to start is what actually lets you fix it. Would love to see the same message that's shown in the Actions UI exposed through either the workflow run API or the check suite API.

[Mohammadshaqboua]

Hey! When a workflow fails with startup_failure, the UI shows the exact reason (e.g. a YAML syntax error on a specific line), but there's no way to get that message via the API.
I checked every relevant endpoint — the run object, jobs, logs, check runs — and none of them expose it. That makes sense since the workflow never parsed, so no jobs or check runs are created. But the error clearly exists server-side since the UI renders it fine.
This is a real pain for us — we have a GitHub App that posts Slack alerts on startup_failure, and right now we can link the run but can't include the actual reason, which is the most useful part.
This was raised back in 2023 (#57536) with no resolution. The only suggested workaround was scraping the run page HTML, which is brittle and breaks on private repos.
The ask: please expose the failure reason somewhere in the API — even just an error or message field on the workflow run or check suite object would be enough.
Thanks!