add missing documentation of use cases for workflowrun states

[tomsit-ionos]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-repository

but should be linked/included on all other pages that are concerned with the WF run status

What part(s) of the article would you like to see updated?

most of the statuses are self explanatory but there is a gray area.

1. Plz provide a description/use case/trigger for each of the statuses, preferably with a state diagram. In particular i would like to know:

   the meaning of these: neutral, stale the difference/relation of these: queued, requested, waiting, pending, action_required

2. Delineate which value belongs to which property as per the above doc:

Additional information

PS: this is a rehash from here: https://github.com/orgs/community/discussions/70540#discussioncomment-10978598

No response

[tomsit-ionos]

btw: i just found this case: "conclusion": "startup_failure"

[nguyenalex836]

@tomsit-ionos Thank you for raising this issue! I'll get this triaged for review :sparkles: Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[github-actions[bot]]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:

[tomsit-ionos]

also it is not quite obvious why the workflow can transition like so:

queued -> in_progress -> queued -> completed

[xxx2585]

Uploading Getting-Started.md…

[nguyenalex836]

@tomsit-ionos Thank you for your patience while our SME team reviewed! Our SME team agrees it would be valuable to have documentation covering these statuses and conclusions.

In terms of ideal location for this new content, we would prefer creating a new reference type of article to Managing workflow runs that defines these, and then link to that article from the API docs.

I've added the help wanted label so that you, or anyone else with knowledge of this area, may work on adding this new content 💛

[luismanac]

want to work on it

[440c]

Is this still being worked on?

[cceneag]

是的我正在參加github的課程有什麼特別還是建議嗎？

ozu @.***>於 2025年6月3日 週二，下午9:01寫道：

440c left a comment (github/docs#34987) https://github.com/github/docs/issues/34987#issuecomment-2935101331

Is this still being worked on?

— Reply to this email directly, view it on GitHub https://github.com/github/docs/issues/34987#issuecomment-2935101331, or unsubscribe https://github.com/notifications/unsubscribe-auth/BSWC2ASU7RADKL5WFY5ZC733BWMCFAVCNFSM6AAAAABQFDLQQWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSMZVGEYDCMZTGE . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[ayushmank]

hi @tomsit-ionos is this issue still opens please let me know i would like to contribute in this

[tomsit-ionos]

Yes this seems to be still open - at least looking at the API that I referenced in the description , still doesn't have an easily accessible link or description to the meaning of the states and their transitions

[ayushmank]

Hi @tomsit-ionos please have a look to this pr [#41379 ] when you have free time thanks !!