It is not clear what values belong to the conclusion or the status fields of a workflow run

Start with the OpenAPI description for the “List workflow runs for a workflow” endpoint and compare its status parameter with the “Get a workflow run” endpoint cited in the issue. Clarify which values belong to status versus conclusion and remove wording that implies conclusion is queryable; the affected endpoint documentation should make the two fields and their usage unambiguous.

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#list-workflow-runs-for-a-workflow

What changes are you suggesting?

Issue 1.

The following values presented on the article linked above:

Can be one of: completed, action_required, cancelled, failure, neutral, skipped, stale, success, timed_out, in_progress, queued, requested, waiting

Are not clearly separated between status and conclusion categories.

The first two lines make the whole paragraph ambiguous:

Returns workflow runs with the check run status or conclusion that you specify. For example, a conclusion can be success or a status can be in_progress

Which seem to indicate that conclusion could also be a query parameter

Expected outcome

Can you please redact the {status} parameter documentation of the API call (see article section):
https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/runs

And separate the values in the list above by assigning them to status and conclusion respectively.

Issue 2.

It also would be great to make sure that conclusion is not misrepresented as a query parameter for that specific API call on the first sentence by using ambiguous language.

Returns workflow runs with the check run status or conclusion that you specify

As we cannot specify a conclusion value as a query parameter, the result is the same as querying for all runs in the workflow. And there's no conclusion parameter indicated.

For example, for a cancelled workflow run the payload contains the following:

Query:
https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run

Response:

"status": "completed",
"conclusion": "cancelled",

Use case

We would like to take a 2 step process where:

1. We find out the status of an specific workflow run
2. Report and FAIL/SUCCEED based on the value in the conclusion

See additional information for more details.

Additional information

It is confusing to tell what to query for in the returned JSON payload when looking at an specific workflow run by id to find out if it was completed or not, since the only text that has an exhaustive list of statuses and conclusions is in the affected article and that text is ambiguous.

This is the query I'm actually using with short polling, the use case is that given a workflow run id, find out when it is completed and report the conclusion by calling this endpoint.

https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID

According to this API call:
https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run

Also, as you can see on the Response schema sections of each api call section the only example given is complete.

P.S.
Instead of recurring to the docs, I had to go outside of the Github docs to find out the disambiguation information I needed:
https://tabris.com/observing-workflow-run-status-on-github/

Value of the status property can be one of: “queued”, “in_progress”, or “completed”. When it’s “completed,” it makes sense to check if it finished successfully. We need a value of the conclusion property. Can be one of the “success”, “failure”, “neutral”, “cancelled”, “skipped”, “timed_out”, or “action_required”.