add missing documentation of use cases for workflowrun states

[tomsit-ionos]

Code of Conduct

• 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 ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[github-actions]

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

[tomsit-ionos]

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

queued -> in_progress -> queued -> completed

[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 💛