Expose the startup_failure reason (invalid workflow file error) via the REST/GraphQL API

[otakuu]

Summary

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 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.

[github-actions[bot]]

Thank you for your interest in contributing to our community! We currently only accept discussions created through the GitHub UI using our provided discussion templates. Please re-submit your discussion by navigating to the appropriate category and using the template provided.

This discussion has been closed because it was not submitted through the expected format. If you believe this was a mistake, please reach out to the maintainers.

[otakuu]

Apologies — this was created via the API by mistake and is correctly auto-closed. Re-submitting through the UI with the provided template. Please disregard.